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OVERLAYING TECHNIQUES 



INTRODUCTION 

Overlays are used to allow a task to be developed and run if the 
amount of memory available or virtual address space for a task is 
insufficient. This module explains the various overlay techniques 
which are available and how to use them. 



OBJECTIVES 

1. To determine whether to use a disk-resident or 
memory-resident overlay in a given situation 

2. To construct overlay structures using the overlay 
descriptor language 

3. To write tasks using overlays. 



RESOURCE 

• RSX-11M/M-PLUS Task Builder Manual, Chapters 3 and 4 
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CONCEPTS 

A task may be too large to fit in the available memory. This may 

happen because it is larger than the total amount of memory on the 

system. More likely, it is because it is larger than the 

partition it is to run in, or the available space within the 

partition. The partition is probably used at the same time by 
other tasks, hence, the available space may be considerably less 
than the full partition. 

For example, a 20K word task may have to fit in 15K words of 

memory. The task can use overlays and load only portions of the 

code at a time and just use 15K words of memory. Typically, the 
pieces which overlay each other contain subroutines. 

As an example, consider a task with main code and two subroutines, 
G and H, which overlay each other. The main code calls subroutine 
G first, causing G's code to be read into memory. Later, the main 
code calls subroutine H, causing H's code to be read into the same 
memory locations, overlaying subroutine G. If the main code later 
calls G, G's code overlays subroutine H. As the task executes, 
overlaying is performed whenever necessary. You can choose to 
have all loading of overlay segments done automatically or you can 
load them manually with specific calls to a loading routine. 

In addition to physical memory limitations, tasks on PDP-11 
systems have virtual memory limitations. As we learned in the 
last module, a task can use a maximum of 32K words of virtual 
addresses at a time. A task may require, say, 40K of virtual 
memory, thereby exceeding the 32K virtual addressing limit. 
Overlays loaded from disk would permit this task to run in 32K 
words or less of physical memory, and allow all of the code loaded 
at any given time to be addressed. Therefore, 32K words, or less, 
of code are loaded and addressed at any one time, satisfying the 
virtual address limit. Or, using a special kind of overlay, all 
40K words of code can be loaded into memory, but the task maps 
only 32K words of code at a time. This means that the task stays 
within the virtual addressing limits even though it uses 40K of 
physical memory. 

These special kinds of overlays are called memory-resident 
overlays. They overlay by remapping rather than by reloading code 
into memory. 
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An overlaid task can have several program segments. A program 
segment consists of part or all of one or more object modules. 
Each of the object modules consists in turn of one or more program 
sections (Psects) . There is always a single resident root 
segment. This segment is loaded when the task is first loaded and 
remains loaded and mapped at all times. In addition, there are 
overlay segments which either: 

reside on disk unless needed and share virtual address 
space and physical memory. 

- stay in memory once needed and share virtual address space 
only. 

There is one restriction on subroutines in an overlay segment. 
They cannot call subroutines which are located in a segment which 
overlays itself. The code for only one segment or the other is 
available at any one time, and never both. We say that the 
segments must be logically independent. 

There are some drawbacks to using overlays. Additional code is 
required to handle the overlay structure and the loading and/or 
mapping of the overlay segments. Also, some execution time is 
required to load and/or map the overlay segments. 



OVERLAY STRUCTURE 

Example 6-1 lists the subroutines (corresponding to overlay 
segments) which each segment calls during the execution of a task. 
In addition, the sizes of the various modules are listed. If the 
task is built without overlays, it is 17K words in size. 

We can reduce the amount of memory needed to 8K words by using 
overlays. Figure 6-1 shows a likely overlay structure, using a 
memory allocation diagram. This picture represents the overlaying 
or sharing of virtual and/or physical address space in the task. 
Figure 6-2 shows another method for showing the same overlay 
structure, an overlay tree. It is easier to draw but doesn't 
allow you to estimate the size of the task. As the calculation 
below Figure 6-1 shows, the largest pieces which will ever be 
needed at any one time are PROG, the root, and overlay segments 
SUB1 and B. These total 8K words, so this task can run in 8K 
words of physical memory. 
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Figure 6-1 A Memory Allocation Diagram 
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STEPS IN PROGRAM DEVELOPMENT USING OVERLAYS 

Use the following steps in developing a task which uses overlays: 

1. Compile each module, producing a .OBJ file for each. 

2. Use the editor to create an overlay descriptor file 
(defines the overlay structure for the Task Builder) . 

3. Task-build using the overlay descriptor file as the only 
input file. 



THE OVERLAY DESCRIPTOR LANGUAGE (ODL) 

The overlay descriptor language (ODL) is a fairly simple language 
which is used to define the overlay structure for the Task 
Builder. Statements are placed in a text file which has a file 
type 'ODL' (e.g., EXAMPLE . ODL) . It is identified to the Task 
Builder as a special file by using the /OVERLAY_DESCRIPTION input 
file qualifier (/MP in MCR) in the task-build command line. 



ODL Command Line Format 

The ODL command lines use the following format: 

label: directive argument-list ;comment 
where : 

label - a one to six character symbolic, required only on a 
. FCTR directive. 

directive - one of the following 

.ROOT - indicates the start of the overlay tree 
.END - indicates the end of input 
.FCTR - allows naming of subtrees 
.NAME - allows naming a segment and assigning 
attributes 

.PSECT - allows special placement of a global 
program section (Psect) - typically 
used only in special cases in MACRO-11. 
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argument list - a list of .OBJ files and/or object 

libraries, separated by hyphens or 
commas, and grouped together with 
parentheses. 

comment - a comment to annotate the line 

The separators have the following meaning: 

• Parentheses 1 () ■ 

enclose the segments to be overlaid 

• The hyphen 1 

indicates the concatenation of virtual address space 

• The comma ' , 1 

- separates the segments to be overlaid 
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Examples of ODL : 

1. X, the root of a task, calls subroutines Y and Z 



.ROOT 
.END 



X-(Y,Z) 



Explanation : 



X is the root segment, Y and Z are each 
overlay segments. Virtual addresses are 
assigned to X first. Starting after that, 
Y and Z begin at the same virtual address 
Either Y or Z (never both) is loaded and 
mapped using those virtual addresses. 



2. Using the information from Example 1, Y calls subroutines U 
and V. 



u 


V 




z 


Y 


X 



.ROOT X-(Y-(U,V) ,Z) 
.END 



Explanation: Add to Example 1. U and V are overlay 

segments which overlay each other. After 
the last address for Y, virtual addresses 
begin for U and V. 



193 



OVERLAYING TECHNIQUES 



Using Example 1 again, add subroutine A to the root segment 



.ROOT X-A-(Y,Z) 
.END 

Explanation: X and A together make up the root segment. 

Virtual addresses are assigned first to X and 
then to A. After that, Y and Z are assigned 
virtual addresses. 



Using ODL to describe Example 6-1 (Figures 6-1 and 6-2) : 

.ROOT PR0G-(SUB1-(A,B) , SUB 2, SUB 3- (C ,D, E) ) 
. END 



Explanation: PROG is the root segment. SUB1, SUB2, and 
SUB3 overlay each other, beginning at the 
same virtual address. A and B overlay each 
other, beginning after SUB1. C, D, and E 
overlay each other, beginning after SUB3. 



Using the . FCTR directive to describe Example 6-1: 

.ROOT PROG- (PARTI, SUB2,PART2) 

PARTI: .FCTR SUB1-(A,B) 

PART 2 : .FCTR SUB3-(C,D,E) 

• END 



Explanation: Substitute SUB1-(A,B) for PARTI in the first 
line. Substitute SUB3-(C,D,E) for PART2 in 
the first line. 



OVERLAYING TECHNIQUES 



TYPES OF OVERLAYS 

There are two types of overlays available, disk-resident overlays 
and memory-resident overlays. In fact, both are loaded from disk. 
The distinction is that disk-resident overlays are always loaded 
from disk every time they are needed, while memory-resident 
overlays are loaded from disk only the first time they are needed. 
After that, they remain in memory and remapping is used to overlay 
segments as needed. 



Disk-Resident 

Disk-resident overlays are available on all RSX-11M systems. See 
Figure 6-3 for an example of a task with a root segment and three 
disk-resident overlays. On initial load, only the root segment 
MAIN is loaded. Overlay segments are loaded from disk whenever 
required. This typically occurs when a subroutine in the overlay 
segment is called. So if the root overlay segment MAIN contains a 
call for subroutine A, for example, segment A is loaded from disk 
prior to the transfer of control to A. If, after the subroutine 
returns control to MAIN, a call is made to subroutine B, segment B 
is loaded into memory right over segment A. If a call is later 
made to subroutine C, segment C is loaded right over segment B. 
This loading of overlay segments is performed whenever necessary. 
The subroutines may be called in any order and each subroutine may 
be called any number of times in the course of task execution. 

The same starting virtual address is assigned to all three overlay 
segments, A, B, and C, beginning at the next 32(10) word boundary 
after the code for MAIN. So A, B, and C use the same virtual 
addresses and are loaded starting at the same physical address. 
One virtual address window maps the entire task, just the code in 
memory is changed when an overlay is loaded. 

This technique is useful when the entire task is too large to fit 
into the space allowed for it. In the example in Figure 6-3, a 
22K word task runs in 15K words of physical memory. Disk-resident 
overlays are the default overlay type. The examples in the 
previous section all produce disk-resident overlays. 
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Figure 6-3 An Example of Disk-Resident Overlays 
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Memory-Resident 

Memory-resident overlays are available only on mapped systems 
which support the memory management directives. See Figure 6-4 
for the same task as in Figure 6-3, this time with memory-resident 
overlays. On initial load, again only the root segment MAIN is 
loaded. The first time an overlay segment is needed it is loaded 
from disk. However, once a segment is loaded it remains in memory 
and is not reloaded from disk. 

If subroutine A is called first, overlay segment A is loaded and 
virtual address window 1 is mapped to A. If, after the subroutine 
returns control to MAIN, a call is made to subroutine B, then 
segment B is loaded, but not directly over A. Instead, it is 
loaded into another area of memory, and then virtual address 
window 1 is mapped to B. If a call is later made to subroutine C, 
segment C is loaded into another area of memory, and virtual 
address window 1 is mapped to C. 

The real gain in run-time efficiency is made when an overlay is 
needed again. If another call is made to A, overlay segment A 
does not have to be loaded again from disk. It is already 
memory-resident. Therefore, virtual address window 1 is simply 
remapped from segment C to segment A. Any additional overlaying 
is performed by remapping, with no further loading of overlay 
segments necessary. Again, the subroutines may be called in any 
order and each subroutine may be called any number of times. 

The advantage of this approach is that after the first load, it is 
much faster than disk-resident overlays. However, there is no 
savings in the use of physical memory. In fact, a bit more memory 
is required than with a non-overlaid task. So its main use is for 
overcoming the 32K word virtual address limit when execution time 
efficiency is important. A 44K word task can use memory-resident 
overlays if there is enough memory available and the time 
necessary for loading disk-resident overlay segments is 
unacceptable . 

The root segment uses one window and each overlay area requires a 
separate window. This means that virtual addresses for each 
overlay segment begin at the starting virtual address for the next 
highest APR, corresponding to a 4K word boundary. Because the 
root segment is 9K(10), APRs 0, 1, and 2 must be used to map the 
root segment. Notice that A, B, and C all begin at virtual 
address 60000, for APR 3. 
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This means that virtual addresses 44000-57777 cannot be used by 
this task. If in fact MAIN were extended, then these virtual 
addresses would be used. Remember, this doesn't mean that any 
physical memory is wasted; but it does mean that careful 
allocation of sizes to the various segments is necessary to avoid 
wasting virtual address space. Note that the maximum number of 
overlay areas with memory-resident overlay is seven since the root 
segment requires one virtual address window and each overlay level 
requires another virtual address window. 

To indicate that you want memory-resident overlays, place an 
exclamation point (!) before an overlay specification. The 1 !' 
applies only to the first level; the next level may have 
disk-resident overlays or memory-resident overlays again. The 
only restriction on mixing of types is that once a level has 
disk-resident overlays, no higher level may have memory-resident 
overlays . 
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PHYSICAL 
MEMORY 



VIRTUAL 
MEMORY 




TK-7767 

Figure 6-4 An Example of Memory-Resident Overlays 
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Examples of .ODL files for memory-resident overlays: 
1. X, the root of a task, calls subroutines Y and Z. 



.ROOT X-! (Y, Z) 
.END 

The 1 makes the overlays memory-resident. 



2. Using the information from Example 1, Y calls subroutines U 
and V. 



u 


V 




Z 


Y 


X 



a. All memory-resident overlays: 

.ROOT X-! (Y-! (U,V) ,Z) 
.END 



b. Some memory-resident overlays, some disk-resident 
overlays : 

.ROOT X-! (Y-(U,V) ,Z) 
.END 



c. Illegal mixture: 

.ROOT X- (Y-! (U,V) ,Z) 
.END 

Explanation of c: This mixture is illegal because the first 
level (Y and Z) is disk-resident. The next higher level 
cannot have memory-resident overlays. Therefore, U and V 
cannot be memory-resident. 
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LOADING METHODS 

There are two loading methods, autoload and manual load. With 
autoload, any necessary loading and/or remapping (in the case of 
memory-resident overlays) is done automatically and is transparent 
to the program. With manual load, the overlay segments are loaded 
by specific user calls to a loading routine. Autoload and manual 
load cannot be mixed in the same task. 



Autoload 

When a call is made to a subroutine in an overlay segment, an 
autoload routine takes control before the transfer to the 
subroutine is made. It checks to find out whether the required 
segment is already loaded or loaded and mapped. It performs any 
necessary loading and/or remapping. Following that, the transfer 
to the called subroutine is made. 

Autoload is path loading, meaning that all segments along the path 
to the required overlay segment are loaded. For example, in 
example 2 in the previous section, involving X, Y, U, V, and Z, if 
a call from segment X is made to subroutine U, both Y and U are 
loaded. (However, the auto-load routine checks to see if either Y 
or U is already in memory and if so, the segments are not loaded.) 

Autoload is indicated by an asterisk (*) before an overlay 
specification in an ODL line. An asterisk outside a set of 
parentheses applies to all levels inside the parentheses. 

The advantages of autoload are that it is easy to use and that it 
does not require changes in the source code. For instance, you 
could make changes in the ODL commands for the task but you would 
not have to make any changes in the source code. One disadvantage 
to autoload is that it increases the size of the segments, since 
the autoload code plus its data structures must be included in the 
task. Another disadvantage is that it executes slower than manual 
load, since the autoload code has to check for whether the 
required segment is available or not each time an autoloadable 
segment is called. In addition, autoload must be performed 
synchronously. See Section 4.1 (on Autoload) in the 
RSX-11M/M-PLUS Task Builder Manual for more information about 
autoload. 
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Examples of autoload: 

1. X, the root of a task, calls subroutines Y and Z. 





Z 


Y 


X 



With disk-resident overlays: 

.ROOT X-*(Y f Z) 
.END 

With memory-resident overlays: 

.ROOT X-*! (Y,Z) 
. END 



2. Using the information from Example 1, Y calls subroutines U 
and V. 



u 


V 




z 


Y 


X 



With disk-resident overlays: 

.ROOT X-* (Y- (U,V) , Z) 
.END 

With memory-resident overlays: 

.ROOT X-*! (Y-! (U,V) , Z) 
.END 

With some memory resident and some disk resident overlays: 

.ROOT X-*! (Y-(U,V) f Z) 
.END 
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Manual Load 

With manual load, you must call the subroutine MNLOAD in the main 
program or any subroutines to load and/or map any required overlay 
segment before calling a subroutine in that segment. 
Additionally, you must keep track of which segments are currently 
available to avoid a transfer of control to an incorrect segment, 
and to avoid unnecessary calls to the loading subroutine. Manual 
load is not path loading. In example 2 of the previous section, 
if X calls U, it can load just segment U, without loading segment 
Y, unless that is desired. See Section 4.2 (on Manual Load) in 
the RSX-11M/M-PLUS Task Builder Manual for more information on 
manual load. 

Manual load is the default loading method. Anytime that a segment 
is not preceeded by an asterisk (*) in the ODL file, manual load 
is used. 

The advantages of manual load are that smaller overlay segments 
result, it is usually more run time efficient, and loading of 
overlay segments can be performed either synchronously or 
asynchronously. The disadvantages are that the user must keep 
track of things and that it requires special coding in the source 
program. 
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Comparison of a Task With No Overlays, With Disk-Resident Overlays, and 
With Memory-Resident Overlays 

Example 6-1, shown earlier in the module, and repeated below for 
convenience, shows a main program which calls a subroutine, which 
in turn calls another subroutine, etc. Note that the sizes shown 
for the various parts of the task are only approximate. 



Main Segment: 



PROG 



PROG calls: 
SUB1 calls: 
SUB2 calls: 
SUB3 calls: 



SUB1, SUB2, SUB3 
A, B 
none 
C, D, E 



Segment Size (in words) 

PROG 4K 

SUB1 2K 

SUB2 3K 

SUB3 IK 

A IK 

B 2K 

C IK 

D 2K 

E IK 

Total 17K 



Example 6-1 Description of an Overlaid Task 



Example 6-2 shows part of the task-build map for the task in 
Example 6-1 when the task is built with no overlays. 

Example 6-3 shows the map when Example 6-1 is built with all 
disk-resident overlays. 

Example 6-4 shows the map when Example 6-1 is built with all 
memory-resident overlays. 

Example 6-2 does not use overlays; therefore no . ODL file is 
required. Examples 6-3 and 6-4 use overlays; therefore they 
require a .ODL file. These files are shown along with the map. 
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Example 6-2 has a root segment but does not have any overlay 
segments. Note that a single virtual address window maps the 
entire task. The virtual address limits of the task are 000000(8) 
and 105357(8), meaning that these virtual addresses are used to 
reference the task code when it is loaded into memory. The task 
image is 17792(10) words long; hence 17792(10) words of physical 
memory are required to load and run the task. 

Task-build command: 

LINK/MAP PR0G,SUB1,A,B,SUB2,SUB3,C, D,E,- 
LB: [1,1] FOROTS/LIBRARY 



Partition name * GEN 

Identification * 01 

Task UIC ! 11305^3013 

Stack limits! 000254 001253 001000 00512* 

PRG xfr address! 021254 

Total address windows* 1* 

Task :i.ma.3e size * 17792* words 

Task address limits J 000000 105357 

R-W disk blk limits! 000002 000107 000106 00070* 



*** ROOT SEGMENT ! PROG 



R/W mem limits! 000000 105357 105360 35568* 
Disk blk limits! 000002 000107 000106 00070* 



Example 6-2 Map File of Example 6-1 Without Overlays 
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Example 6-3 with disk-resident overlays, has a root segment, PROG, 
and eight overlay segments. Note that a single virtual address 
window maps the entire task when just disk overlays are used; 
i.e., when no memory resident overlays are used. The overlay 
description shows the virtual addresses and sizes of the segments. 
On the right side, the segments are listed, lined up by overlay 
level. Segments SUB1, SUB2, and SUB3 overlay each other. They 
all begin at virtual address 022200(8), right after the root 
segment PROG. At various times, virtual addresses starting at 
022200(8) reference the memory code of the overlay segment which 
is actually loaded in memory at that time. 

Segments A and B overlay each other, beginning with virtual 
address 032234(8), right after SUB1. In a similar way, segments 
C, D, and E begin at virtual addresses 026250(8), right after 
SUB3. With disk-resident overlays, only virtual addresses 
000000(8) to 042237(8) are used to reference the task in memory, 
compared to 0000000(8) to 105357(8) without overlays. This task 
requires only 8800(10) words of memory, compared to 17792(10) 
words with no overlays. 
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PROG.ODL file: 

.ROOT PROG-L-* (SUB1-L-(A-L,B-L) , SUB2-L , SUB3-L- (C-L , D-L , E-L) ) 
L: . FACTR LB : [1,1] FOROTS/LIBRARY 
.END 

Task-build command: 

LINK/MAP PROG/OVERLAY_DESCRIPTION 

Note that LB: [1 , 1] FOROTS/LIBRARY must be concatenated with each 
segment in the ODL file. In the remaining examples of ODL files, 
the concatenation of the library to each segment will not be shown 
in order to simplify the appearance of the ODL file. 



Partition name * GEN 

Identification * 01 

T3sk UIC ♦ C305y3013 

Stack limits? 000260 001257 001000 00512* 

PRG xfr address ♦ 021260 

Total address windows* 1* 

Task image size * 8800* words 

Task address limits: 000000 042237 

R~W disk blk limits: 000002 000120 000117 00079* 



11X63 *TSK Overlay description* 



Base 


Top 


Length 






000000 


022177 


022200 


09344* 


PROG 




022200 


032233 


010034 


04124* 


SUB1 




032234 


036237 


004004 


02052* 




A 


032234 


042237 


010004 


04100* 




B 


022200 


036203 


014004 


06148* 


SUB2 




022200 


026247 


004050 


02088* 


SUB3 




026250 


032253 


004004 


02052* 




C 


026250 


036253 


010004 


04100* 




D 


026250 


032253 


004004 


02052* 




E 



Example 6-3 Map File of Example 6-1 With Disk-Resident Overlays 
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Example 6-4, with memory-resident overlays, also has a root 
segment, PROG, and eight overlay segments. Notice that three 
virtual address windows are required for this task, one for the 
root segment and one for each other overlay level. PROG uses 
virtual addresses 000000(8) to 023077(8), slightly more than with 
Example 6-3. However, segments SUB1, SUB2, and SUB3 begin at 
virtual address 40000(8) corresponding to the next available APR, 
APR 2, and not right after PROG. This is necessary because the 
virtual address window must begin with the next APR. Segments A 
and B begin at 60000(8), since the next virtual address window 
begins with APR3. Segments C, D and E also begin at 60000(8) for 
the same reason. With memory-resident overlays, virtual addresses 
000000(8) to 077777(8) are used and the task requires 18464(10) 
words in memory. The memory-resident overlay version of the task 
requires the most virtual memory and also the most physical memory 
of the three examples. 
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PROG.ODL file: 

.ROOT PROG-*! (SUB1-! (A, B) ,SUB2,SUB3-! (C,D,E) ) 
. END 

Task-build command: 

LINK/MAP PROG/OVERLAY DESCRIPTION 



Partition name ♦ GEN 

Identification * 01 

Task UIC i C305v3013 

Stack limits? 000320 001317 001000 00512* 

PRG xfr address: 021320 

Total address windows* 3* 

Task image size ♦ 18464* words 

Task address limits? 000000 077777 

R~W disk blk limits: 000003 000122 000120 00080* 



EXDOVR.TSK Overlay description: 



Base 


Top 


Length 






000000 


023077 


023100 


09792* 


PROG 




040000 


050077 


010100 


04160* 


SUB1 




060000 


064077 


004100 


02112* 




A 


060000 


070077 


010100 


04160* 




B 


040000 


054077 


014100 


06208* 


SUB2 




040000 


044077 


004100 


02112* 


SUB3 




060000 


064077 


004100 


02112* 




C 


060000 


070077 


010100 


04160* 




D 


060000 


064077 


004100 


02112* 




E 



Example 6-4 Map File of Example 6-1 With Memory-Resident Overlays 
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Table 6-1 refers to Examples 6-2, 6-3, and 6-4. 



Table 6-1 Comparison of Overlaying Methods 



Method 



Task Size 



Windows 



Advantages and 

Disadvantages 



Non-Overlaid 17792(10) Words 1 

of Memory 



Di sk-Resident 



70(10) Blocks 
on Disk 

105360 (8) 
Vi rtual 

Addresses Used 



8800(10) Words 
of Memory 

79(10) Blocks 
on Disk 



42238 (8) 
Virtual 

Addresses Used 



Memory-Resident 18464(10) Words 

of Memory 

80(10) Blocks 
on Disk 



100000 (8) 
Virtual 

Addresses Used 



Advantages 

Smallest task size on 
disk 

Fastest execution 
Simplest to develop 

Disadvantages 

Maximum task size 32K 
words 

Task smaller than 32K 
words but too large 
for partition or for 
available space in 
partition 

Advantages 

Uses the smallest 
amount of physical 
memory 

Uses the least amount 
of virtual address 
space 

Disadvantages 

Slowest execution 
time; overlay segments 
loaded from disk when 
needed 

Advantages 

Faster execution than 
disk-resident over- 
lays 

Task resident in 
memory at one time 

Disadvantages 

Uses the most memory 
and disk space 
May waste virtual 
address space 
Requires space in 
memory to hold the 
entire task 
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Table 6-1 gives a comparison of the three overlaying methods. In 
addition to the various sizes, it also lists the advantages and 
disadvantages of each approach. It is also possible to build this 
task with memory-resident overlays for the first level (SUB1,SUB2 
and SUB3) and disk-resident overlays for one or both of the second 
levels (A and B; or C, D and E) . 



LIBRARIES 

Object libraries, when used, must be specified in the .ODL file. 
The one exception is the default system library 
LB: [1 , 1] SYSLIB. OLB, which is searched automatically for the root 
and each overlay segment. To allow inclusion of any needed 
libraries, just specify the library with the /LB qualifier (as in 
MCR format for TKB) . To force the inclusion of a specific module 
from a library, use the /LB:module form of the /LB qualifier. 



Examples : 
1. 

.ROOT MAINPG-MYLIB1/LB-LIB- (SUBA, SUBB,CPART) 
CPART: . FCTR SUBC1- (SUBC2 , SUBC3) 

LIB: .FCTR MYLIB2/LB 

.END 

Explanation: Include all needed modules from MYLIB1.0LB 
and from MYLIB2 . OLB that are referenced in 
the root segment MAINPG. 

2. 

.ROOT MAIN-MYLIB1/LB :M0D4-MYLIB1/LB- (A,B) 
.END 

Explanation: Include the module M0D4 from MYLIB1 . OLB . 

In addition, the second MYLIB1/LB with no 
modules listed, causes the inclusion of 
any other modules from MYLIB1 . OLB that 
are referenced in the root segment MAIN. 



Note that if you reference additional library routines 

from other segments, they will not get resolved properly 

unless you specify the library again in each referencing 
overlay segment. 
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3. 



Including the FORTRAN OTS Library: 



LIBRA: 



.ROOT 
. FCTR 
.END 



MAIN-LIBRA- (A-LIBRA f B-LIBRA) 

LB: [1 , 1] FOROTS/LB or F4POTS/LB 



Include needed modules from FOROTS.OLB (or F4POTS.OLB) in the root 
segment, in segment A, and in segment B. Notice that you should 
specify the library in each segment which might need it. 
Otherwise, if segment A needs a module not already included for 
the root segment, the library is not searched again for module A 
unless it is specified again in overlay segment A. 

Note that in an installation which makes heavy use of FORTRAN, the 
appropriate FORTRAN OTS library may have been included in SYSLIB 
making it unnecessary to include the OTS library in the TKB 
command. Check with your system manager to see if the OTS library 
is included in SYSLIB. 

Example of Duplicate Code in Overlays 

In the above example with a root and two overlay segments, A and 
B, it is possible that duplicate code will be forced into the two 
segments. If A and B both need module X from' the library, and the 
root does not need X, then a copy of X would be placed in both 
segment A and in segment B. This adds to the size of segments A 
and B but keeps the size of the root smaller. If the size of the 
root is critical, you may be willing to have the duplicate code 
appear in A and B. If the size of the root is not critical, force 
X to be in the root by the following ODL statement: 



In general, it is good practice to include a library reference in 
each segment of the task. If you are concerned with the 
possibility of duplicate code, you can use the trial and error 
approach wherein you specify the library only in the root and then 
note the unresolved symbols that occur. Once you determine from 
the TKB map which modules are needed in which segments, you can 
then determine if you want to place certain modules in the root or 
if you are willing to have duplicate code in various segments. 



LIB: 



. ROOT MAIN-LB : [ 1 , 1 ] FOROTS/LB : X-LIB- ( A-LIB , B-LIB ) 

. FCTR LB : [ 1 , 1 ] FOROTS/LB 

.END 
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Duplicate code can also be included from SYSLIB, the default 
library. If you wish to use the trial and error method on modules 
from SYSLIB, use the /LONG qualifier in the LINK command (/MA in 
TKB format) . This qualifier causes the Task Builder to list 
modules included from SYSLIB in the map file. 

Note that in the previous example, if X had been required in the 
root, duplicate code in the overlay segments would not be 
generated; all references to X would be resolved via the root. 



An Overlay Example 

Example 6-5 is a simple task with a root segment ROOT and 2 
overlay segments, P and Q. During the execution of the task, the 
following calling sequence is used: 

ROOT calls P 
ROOT calls Q 

Figure 6-5 shows an overlay tree and a memory allocation diagram 
for this task. 

The code for Example 6-5 is separated into three different 
modules, one for each segment. The source file for the root 
segment ROOT contains the startup code and controls the overlay 
loading by calls to the subroutines. The source file for each 
overlay segment, P and Q, contains the subroutine code. 



OVERLAY TREE 

MEMORY ALLOCATION DIAGRAM 



P Q 


P 


Q 


1 | 1 
ROOT 


ROOT 



TK-7755 



Figure 6-5 Task with Two Overlay Segments 
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Steps in Program Development for Example 6-5 

1. Compile each module. 

>FORTRAN/LIST ROOT 
> FORTRAN/LI ST P 
> FORTRAN/LI ST Q 



2. Use the editor to create the overlay descriptor file 
FEXDOVR. ODL for disk-resident overlays. 

.ROOT ROOT-LIB-* ( P-LIB , Q-LIB) 
LIB: . FCTR LB : [ 1 , 1 ] FOROTS/LB 
. END 



3. Task-build using the .ODL file as the input file. 
>LINK/MAP EXDOVR/ OVERLAY DESCRIPTION 



LEARNING ACTIVITY 

1. To build the above task with 
memory-resident overlays, how would you 
modify the .ODL file? 

2. To build the above task without overlays, 
what task-build command would you use? 
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The following notes are keyed to Example 6-5. 

O On initial load only the root segment ROOT is loaded. 

Q With autoload the call to subroutine P causes the autoload 
routine to load overlay segment P from disk and then 
transfer control to the subroutine. 

Q Subroutine P displays a message and returns. 

Q The call to subroutine Q causes the autoload routine to 
load overlay segment Q from disk over segment P and then 
transfer control to the subroutine. 

Q Subroutine Q displays a message and returns. 

If another call were added to subroutine Q, the autoload routine 
would check and see that overlay segment Q is already loaded and 
would then just transfer control to Q. If another call were added 
to subroutine P, the autoload routine would check and see that 
overlay segment P is not loaded. Hence, it would load segment P 
over segment' Q and then transfer control. 
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PROGRAM ROOT 

C 

C FILE ROQT.FTN 
C 

C This task calls each of the subroutines P AND Q 
C 

C Task-build instructions* Use FEXDGVR ♦ ODL as the input 

C file* 

C 

WRITE (5s»50) ! Display message 

50 FORMAT (' THE ROOT SEGMENT IS NOW RUNNING AND 

1WILL CALL P*'> 
CALL P 

WRITE <5j>150) ! Display message 

150 FORMAT (' THE ROOT SEGMENT WILL NOW CALL Q*') 

CALL Q 

WRITE (5*250) ! Display message 

250 FORMAT (' THE ROOT SEGMENT WILL NOW EXIT*') 

CALL EXIT ! Exit 

END 



SUBROUTINE P 

C 

C FILE P ♦ FTN 
C 

C This subroutine displays a message and then returns 
C 

WRITE (5? 50) ! Display message 

50 FORMAT (' SEGMENT P IS NOW LOADED* SUBROUTINE P 

IIS EXECUTING* ' ) 

RETURN ! Return 

END 



SUBROUTINE Q 

C 

C FILE Q.FTN 
C 

C This subroutine displays a message and then returns 
C 

WRITE (5? 50) ! Display message 

50 FORMAT (' SEGMENT Q IS NOW LOADED* SUBROUTINE Q 

IIS EXECUTING* ' ) 

RETURN ! Return 

END 



Run Session 
>RUN EXDGVR 

THE MAIN SEGMENT IS RUNNING AND WILL CALL P* 
SEGMENT P IS NOW LOADED* SUBROUTINE P IS EXECUTING* 
THE MAIN SEGMENT WILL NOW CALL 0* 

SEGMENT Q IS NOW LOADED* SUBROUTINE Q IS EXECUTING* 
THE MAIN SEGMENT WILL NOW EXIT* 



Example 6-5 A Task with Two Overlay Segments 
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Changing Example 6-5 to Manual Load 

To change the previous example to manual load, the source code in 
ROOT must be modified to include the calls to subroutine MNLOAD 
which will cause the loading of the segments. The ODL file must 
also be modified to remove the autoload indicator (*) . The files 
MLROOT. FTN and MLEXDOVR. ODL on the tape provided with this course 
are modifications of ROOT. FTN and EXDOVR.ODL. Check UFD [202,3] 
for these files. See your course administrator if you have 
difficulty finding these files. 



GLOBAL SYMBOLS IN OVERLAID TASKS 

When the Task Builder builds a task, each reference to a 
subroutine is an unresolved symbol reference which must ultimately 
be resolved by finding a corresponding subroutine or by finding an 
entry in the system library. (Each subroutine generates a global 
symbol definition which can be used to resolve an unresolved 
global reference symbol.) If no such subroutine or entry in the 
system library is found, the global symbol is unresolved. 

The scope of a global symbol is controlled by the overlay 
structure. A module can only refer to a global symbol defined on 
a path which passes through it. Thus, in Figure 6-6, the 
reference to global symbol R (global symbol and subroutine are 
used synonymously in this discussion) in segment Al is undefined 
because R is not defined in either A0 or CNTRL. A0 and CNTRL form 
the only path passing through Al. The definition in A2 can't be 
used because Al and A2 overlay one another. 

In a single segment task with no overlays the same global symbol 
cannot be defined more than once, or it is multiply defined. With 
the rules governing global symbols in overlays, however, the same 
name can be used for two different global symbols as long as they 
follow these two restrictions: 

1. They must be defined on separate paths. Each reference is 
resolved to the definition on its own path. Only if the 
same symbol is defined more than once on the same path, is 
it multiply defined. 

2. The two symbols must not be referenced from a segment 
closer to the root which has paths through both segments. 
An example is a root segment which references a subroutine 
N. If the root segment has two overlay segments U and V 
and each one defines the subroutine N, the Task Builder 
can't tell which subroutine N to use. Therefore, the 
reference is ambiguous, since there are several possible 
ways to resolve the reference. 



217 



OVERLAYING TECHNIQUES 



Figure 6-6 shows an example overlay tree with a number of global 
symbol definitions. The various references are resolved as 
follows : 



Q is defined in A0 and B0 



Reference in A22 resolved in A0 
Reference in Al resolved in A0 
Reference in Bl resolved in B0 



R is defined in A2 



S is defined in A0 and B0 



T is defined in A0 and A21 



Reference in A22 resolved to A2 
Reference in Al undefined 
Reference in CNTRL resolved to A2 
(if autoload, through an autoload 
vector) 

Reference in Al resolved to A0 
Reference in A21 resolved to A0 
Reference in A22 resolved to A0 
Reference in Bl resolved to B0 
Reference in B2 resolved to B0 
Reference in CNTRL ambiguous 

Symbol multiply defined 



A1 

Q(REF) 
R(REF) 
S(REF) 



A21 

T(DEF) 
S(REF) 



A22 

R(REF) 
Q(REF) 
S(REF) 



A2 
R(DEF) 



AO 



JL1 
Q(REF) 
S(REF) 



B2 
S(REF) 



BO 



Q(DEF) 


Q(DEF) 


S(DEF) 


S(DEF) 


T(DEF) 

I 







CNTRL 

S(REF) 
R(REF) 



Figure 6-6 Resolution of Global Symbols 
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Data References in Overlays 

Data local to an overlay segment is only available while the 
segment is loaded. When the segment is overlaid by another 
segment, any updating of local data that had been made while the 
segment was loaded will be lost. The next time the same segment 
is loaded from the disk, the original data values will be brought 
into memory. For this reason it is strongly recommended that data 
required by more than one segment be placed in the root. 

If you wish to share data between overlay segments, you must use 
FORTRAN COMMON or pass arguments in the CALL (discussed below) . 
Note that if you want to share data between overlay segments A and 
B, and if updating of the data can be done by either segment, it 
is not sufficient to simply place the COMMON in A and B; it must 
also be placed in the root segment. 

By placing the same COMMON in the root, you are assured that A and 
B will always be referring to the same data in the COMMON since 
the root segment is always loaded. In FORTRAN-77 another way to 
place a COMMON in the root is to use the FORTRAN SAVE common-name 
statement in one of the segments. This will force the 
task-builder to place the named common in the root. The .PSECT 
ODL statement can also be used to force the placement of a common 
in the root segment. 

Another way of sharing small amounts of data between two overlays 
is to have the data passed from the root to each overlay as an 
argument to the CALL. If the segment changes one of the data 
values passed as an argument, it will then be changed in the root 
segment. The changed value can then be passed to the next 
overlay, etc. 

Example 6-6 is a more complex example of the use of overlays. The 
program calling sequence is as follows: 

MAIN calls A 

A calls J0B1 or J0B2 (in module JOBXX) 

MAIN calls B 

Loop through three time 

MAIN calls A 

A calls J0B1 or J0B2 
End of loop 

MAIN calls TOTAL (in the root segment) 
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The following notes are keyed to Example 6-6. 
Q Task-build instructions. 

O COMMON OTHER is defined in the root segment MAIN , and is 
referred to in overlay A and in overlays J0B1 and JOBXX. 
The entire allocation of space for OTHER is in MAIN; no 
space is reserved for OTHER in the overlays. 

The use of the COMMON OTHER by the MAIN segemnt and the 
the overlay segments allows the overlays to access data 
provided by MAIN and to pass a result back to MAIN via the 
fourth argument in OTHER. This argument is called 
variously ANS in MAIN, ARG ( 4 ) in overlay A, SUM in overlay 
J0B1 and ANS in JOBXX. 

COMMON TOTCOM is also defined in MAIN and is referenced in 
overlays J0B1 and JOBXX. Allocation for TOTCOM is in 
MAIN. Subroutine TOTAL displays the grand total, which 
has been accumulated in TOTCOM in variable TOT, but the 
subroutine does not refer to COMMON TOTCOM. Since MAIN 
passes the argument TOT to subroutine TOTAL, the 
subroutine does not have to use TOTCOM. This illustrates 
how shared data may be passed between overlay segments via 
the argument list. 

Q Note that subroutine A calls J0B2, which is the name of 
the subroutine, and that the ODL file uses JOBXX which is 
the file name. File names are always used in ODL; not 
subroutine names. In general, file names and subroutine 
names should be the same simply to avoid confusion. 

Note that neither COMMON OTHER or COMMON TOTCOM appear in 
segment B since the segment does not refer to any 
variables in either COMMON. 

Q Argument TOT is is COMMON TOTCOM. Since the argument is 
passed to subroutine TOTAL, TOTAL does not need a 
reference to COMMON TOTCOM. 
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PROGRAM MAIN 
FILE MAIN *FTN 

This program prints a message and then calls subroutine 
A* Subroutine A asks whether to perforin Job 1 or Job 2* 
It then calls either subroutine J0B1 or J0B2 which 
performs the operation and displays the results* MAIN 
then calls subroutine B which displays a message* MAIN 
then calls subroutine A 3 more times* keeping 3 grand 
total of the operations* Finally? it displays the 
grand total and exits* 

Task-build instructions* Use FMRMAIN*ODL as the input 
file* 



COMPLEX DUMMY (1024) ! Leave space to make 

! segment larger 
COMMON /0THER/0P1 yOPyOP2y ANS 
INTEGER 0Ply0P»0P2*ANS 
DATA 0Pl*0P2/5v2/ 



O COMMON /T0TC0M/T0T 
INTEGER TOT 



! Total 



C 
10 



TYPE ** 'THE MAIN 
CALL A 

TYPE *y 'THE MAIN 
CALL B 

DO 10 f I--l*3 
TYPE ** 'THE MAIN 
ANS = 

TYPE * ? ' THE MAIN 
CALL TOTAL (TOT) 

TYPE *y 'THE MAIN 

CALL EXIT 

END 



SEGMENT IS RUNNING AND WILL 

! Call subroutine A 
SEGMENT WILL NOW CALL B ' 

! Call subroutine B 

SEGMENT WILL NOW CALL A ' 

Clear answer in case 

of no operation 
Call subroutine A 
SEGMENT WILL CALL TOTAL' 
! Call routine to 
! display grand total 
SEGMENT WILL NOW EXIT ' 
! EXIT 



Example 6-6 Complex Example Using Overlays 
(Sheet 1 of 4) 
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SUBROUTINE A 

c 

C FILE A ♦ FTN 
C 

C This subroutine displays 3 message and then asks which 
C of two Jobs to do* It calls the appropriate subroutine 
C to do the Job* displays the results * and then returns 
C to the main program 
C 



3 



.1.0 

20 
21 

1000 
.1.001 
2000 



COMMON /0THER/ARG 
INTEGER ARG<4) 
INTEGER BUFF 



TYPE 1 
FORMAT 
1 A IS 
TYPE 2 
FORMAT 
1? ' ) 
ACCEPT 
FORMAT 



(T8j» "SEGMENT 
EXECUTING* ' > 



A IS NOW LOADED* SUBROUTINE 



<'$'*TS*'D0 YOU WANT TO DO JOB 1 OR JOB 2 



3 t BUFF 
(16) 

IF (BUFF*NE* 1 ) GOTO 10 
CALL J0B1 
GOTO 20 

IF (BUFF*NE*2) GOTO 1000 
CALL J0B2 
TYPE 21 y ARG 

FORMAT (T8»I2»lXi.A2yI2y ' 
GOTO 2000 
TYPE 1001 

FORMAT (TSy'NO SUCH JOB* 

RETURN 

END 



Is it Job 
Call subr 
Branch to 
Is it Job 
Call subr 

* 'yI3/) 



SORRY* ' ) 
Return 



1? 

to do Job 1 
display code 
2? 

to do Job 2 



Example 6-6 Complex Example Using Overlays 
(Sheet 2 of 4) 
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SUBROUTINE JOB1 
FILE JOBl*FTN 

This {subroutine performs an addition operation* The 
operands r operator* 3nd sum are held in one common 
block* and the total in another* 

COMMON /0THER/NUM1 •> OPRATR * NUM2 9 SUM 

INTEGER NUM.! t OPRATR 9 NUM2 9 SUM 
COMMON /TOTCOM/TOT 

INTEGER TOT 



INTEGER DUMMY (1024) 



TYPE 1 



! Leave space to make 
! module larger 

! Display message 



FORMAT <T16* "SEGMENT J0B1 IS NOW LOADED* '9 
1/*T16'SUBR0UTINE J0B1 IS EXECUTING ♦ ' ) 
SUM = NUM1 + NUM2 



TOT = TOT 
OPRATR * 

RETURN 
END 



+ SUM 
+ ' 



Calculate sum 
Add to grand total 
Move operand for 
output display 



SUBROUTINE J0B2 
FILE J0BXX*FTN 

This subroutine performs a multiplication operation* 
The operands* operator 9 and product are held in one 
common block 9 the running total in another* 

COMMON /0THER/0P1*0PRATR»0P2*ANS 

INTEGER 0P1 9 OPRATR 9 0P2 9 ANS 
COMMON /TOTCOM/TOT 

INTEGER TOT 



REAL DUMMY ( 1024) 



Leave space to make 

module larger 
Display message 



TYPE 1 

FORMAT (T16* "SEGMENT JOBXX IS NOW LOADED* " 9 
1/*T16* 'SUBROUTINE J0B2 IS EXECUTING* ' > 



ANS ™ 0P1 * 0P2 
TOT « TOT + ANS 
OPRATR « '*" 

RETURN 
END 



Calculate product 
Add this to grand total 
Move operand for 
output display 



Example 6-6 Complex Example Using Overlays 
(Sheet 3 of 4) 
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SUBROUTINE B 

c 

C FILL" B *FTN 
C 

C This subroutine displays a message and returns 
C 

TYPE 1 

:L FORMAT <T8y 'SEGMENT B IS NOW LOADED* SUBROUTINE 

IB IS EXECUTING ♦ ' ) 
RETURN 
END 



Q SUBROUTINE TOTAL (TOT) 

C FILE TOTAL * FTN 
C 

C Subroutine to display grand total* The grand total 

C location is passed as a subroutine argument 

C 

INTEGER TOT 
TYPE 1>T0T 

:l. FORMAT (' THE GRAND TOTAL IS ' >I3»'.'/) 

RETURN 
END 



Run Session 



>RUN MRMAIN 

THE MAIN SEGMENT IS RUNNING AND WILL CALL A 

SEGMENT A IS NOW LOADED* SUBROUTINE A IS EXECUTING ♦ 

DO YOU WANT TO DO JOB 1 OR JOB 2? 1 
SEGMENT JOB1 IS NOW LOADED* 
SUBROUTINE J0B1 IS EXECUTING ♦ 

5 + 2 = 7 



THE MAIN SEGMENT WILL NOW CALL B 

SEGMENT B IS NOW LOADED. SUBROUTINE B IS EXECUTING* 
THE MAIN SEGMENT WILL NOW CALL A 

SEGMENT A IS NOW LOADED* SUBROUTINE A IS EXECUTING. 
DO YOU WANT TO DO JOB 1 OR JOB 2? 2 
SEGMENT JOBXX IS NOW LOADED. 
SUBROUTINE J0B2 IS EXECUTING* 
5 * 2 = 10 



THE MAIN SEGMENT WILL NOW CALL A 

SEGMENT A IS NOW LOADED. SUBROUTINE A IS EXECUTING. 
DO YOU WANT TO DO JOB 1. OR JOB 2? 2 

SEGMENT JOBXX IS NOW LOADED. 

SUBROUTINE J0B2 IS EXECUTING. 
5 * 2 = 10 

THE MAIN SEGMENT WILL NOW CALL A 

SEGMENT A IS NOW LOADED. SUBROUTINE A IS EXECUTING. 
DO YOU WANT TO DO JOB 1 OR JOB 2? 1 
SEGMENT J0B1 IS NOW LOADED. 
SUBROUTINE J0B1 IS EXECUTING. 
5 + 2 * 7 



THE MAIN SEGMENT WILL CALL TOTAL 
THE GRAND TOTAL IS 34. 

THE MAIN SEGMENT WILL NOW EXIT 



Example 6-6 Complex Example Using Overlays 
(Sheet 4 of 4) 



224 



OVERLAYING TECHNIQUES 



LEARNING ACTIVITY (Using Example 6-6) 

1. Draw an overlay tree or a memory 
allocation diagram. Since the questions 
below assume a particular overlay 
structure, check your answer before doing 
questions 2 through 4. 

2. What . ODL file would you use for autoload 
and all disk-resident overlays? 

3. What .ODL file would you use for autoload 
and all memory-resident overlays? 

4. What .ODL file would you use for autoload 
and A and B memory-resident and J0B1 and 
JOBXX disk-resident? 



CO-TREES 

Sometimes there are subroutines which must be callable from 
several or all different overlay segments in a task. One solution 
is to place the subroutines in the root. Since they are always 
loaded, they are then available from the root and all overlay 
segments. If this causes the task to become too large and the 
subroutines are logically independent (don't call each other), 
another solution is available. You can set up a separate overlay 
area and place the subroutines in it so that they overlay each 
other. 

For example, Figure 6-7 shows an overlaid task with subroutines X 
and Y in the root. They are placed there so that the root and 
every other segment can call them. If this makes the task too 
large, set up a separate overlay area and place X and Y in it so 
they overlay each other (Figure 6-8) . X and Y are in a separate 
overlay area, therefore, they can overlay each other and still be 
called from the root and every other segment in the task. 
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The two overlay areas, the main one and the separate one for the 
extra subroutines, are defined by a multiple tree structure. The 
tree for the main code is called the main tree and the other one 
is called a co-tree. The co-tree root may contain code but it 
does not have to. In the example in Figure 6-8, the root of the 
co-tree is null (or is a dummy root) and contains no code. A root 
is needed to set up the overlay structure. Only the root of the 
main tree is loaded on initial load. The co-tree roots are loaded 
when they are first needed and remain loaded after that. Other 
than that, loading of overlay segments works just like a 
single-tree overlay structure. 

The . ODL files are listed above the files for the task without 
co-trees and with co-trees. The co-trees are separated in the 
.ODL file by a comma. With autoload, an asterisk (*) should be 
specified on the co-tree roots as well as in the normal places. 
This is necessary because the co-tree roots are loaded like 
overlay segments the first time they are needed. Also, note that 
the .NAME directive is used to specify that CNTRL2 is just a name 
for the null root segment of the co-tree. 

For additional information on co-trees and an example, see Section 
3.5 (on Multiple-Tree Structures) in the RSX-11M/M-PLUS Task 
Builder Manual . In particular, note the use of the /NOFU or /FU 
switch used with TKB. 
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.ODL File with no co-trees: 

.ROOT CNTRL-X-Y-* (A0, (A1,A2) ,B0-(B1,B2) ) 
.END 



A1 A2 B1 B2 

L - H L -r- 1 

AO BO 

Y 
I 

X 
I 

CNTRL 





A2 


B1 




A1 


B2 


BO 


AO 



Y 



X 



CNTRL 



TK-8635 

Figure 6-7 Task Without Co-Trees 
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. ODL File with Co-Trees 
.NAME CNTRL2 

.ROOT CNTRL-* (A0-(A1,A2) ,B0-(B1,B2) ) , *CNTRL2- *(X,Y) 
.END 

The segment CNTRL2 is a dummy root used for loading purposes only. 



A1 A2 B1 B2 

H ' i ' 

AO BO X 



CNTRL CNTRL2 



A1 



A2 



AO 



B1 



B2 



BO 



CNTRL 



NULL ROOT CNTRL2 



Figure 6-8 Use of Co-Trees 
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Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all lab problems. Check your answers against the 

solutions provided, either in that book or in on-line files. 

If you think that you have mastered the material, ask your course 

administrator to record your progress in your Personal Progress 

Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, return 

to this module for further study. 
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INTRODUCTION 

Logical address space in a task is composed of regions. There are 
three basic types of regions: task regions, static regions, and 
dynamic regions. Task regions, into which tasks are loaded, are 
created using information set up by the Task Builder. Static and 
dynamic regions are generally used to share code or data among 
several tasks. Static regions are created using the Task Builder; 
dynamic regions are created during task execution using executive 
directives. 

This module discusses static regions. You can use these static 
regions to: 

• Create memory areas containing code which is shared among 
tasks 

• Create memory-resident data areas which can be used for 
communication between tasks or successive invocations of 
the same task. 



OBJECTIVES 

1. To create and use a resident common region 

2. To create and use a resident library 

3. To determine whether a position independent or an absolute 
shared region should be used in a given situation. 



RESOURCE 

• RSX-11M/M-PLUS Task Builder Manual, Chapter 5 



♦ 
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TYPES OF STATIC REGIONS 

Static regions, also called shared regions, are areas of memory 
which are shared among tasks. They allow tasks to share data or 
code with very little overhead. Unlike send and receive 
directives, no executive directives are needed and the area's size 
is limited only by virtual address and possibly physical memory 
limitations. The virtual addressing limit must be met for both 
the region itself and for any tasks which use the region. For a 
task using the region, the virtual addressing limit applies to the 
total of all regions used plus the task's code. 

Static regions also offer very quick access, since the area is 
loaded before the tasks which use it are run. Once loaded, it is 
available directly in memory. Therefore, it offers much faster 
access than disk-resident data. 

Table 7-1 summarizes the types of shared regions available on an 
RSX-11M system. A resident common contains data. The data can be 
accessed by several different tasks, each with read only access or 
with read/write access. 

A resident library contains reentrant subroutines, which can be 
called by several different tasks. A single copy of each 
subroutine can be shared, thus reducing the total memory 
requirements of the tasks. The term resident is used because the 
shared region is task-built, installed, and 'loaded into memory 
separately from the tasks which access it. 

A third type of shared region is a device common, a special type 
of resident common. It occupies physical addresses on the I/O 
page, which correspond to I/O device registers instead of physical 
memory. Therefore, this kind of common allows a task to reference 
an I/O device directly. Unlike other resident commons, a device 
common has no true contents because it has no physical memory 
associated with it. 
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Table 7-1 Types of Static Regions 
Available on RSX-11M 



Type of Region 



Contents 



Advantages 



Resident Common 



Data accessed 
by two or more 
tasks 



Serves as com- 
munications link 
Serves as memory- 
resident data base 



Resident Library 



Device Common 



Reentrant routines, 
used by two or more 
tasks (must be wri- 
ten in MACRO-11 but 
can be used in a 
FORTRAN CALL) 

No true "contents" 
Region is a range 
of physical addresses 
within I/O page 



One copy of common 
routines shared in 
memory 



Nonpr ivileged task 
can directly access 
an I/O device with- 
out being mapped 
to the Executive 



MEMORY ALLOCATION 

Memory is allocated independently to the shared region and to the 
individual tasks which use it. We will call the tasks which use 
the region referencing tasks. On an RSX-11M system, the shared 
region must reside in a dedicated common type partition. The name 
of the partition must be the same as the name of the region. The 
partition can be created at SYSGEN time or later by the system 
manager or by a privileged user. Once the region is installed and 
loaded into the partition, it cannot be checkpointed . 
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MAPPING 

Shared regions can be written and task-built as either position 
independent regions or as absolute regions. On a mapped system, 
position independent regions can be placed anywhere in a 
referencing task's virtual address space. This means that the 
virtual addresses used to map to the region can correspond to any 
available APR. 

Figure 7-1 shows a position independent region POSIND and three 
referencing tasks. The region is loaded into memory into the 
partition POSIND; the partition name must be the same as the name 
of the region. Recall that a virtual address window for mapping 
must begin with a base address for an APR on a 4K word boundary. 
Because the region is 5K words in length and each APR can only map 
at most 4K words, two APRs are needed to map the region. 

TASK A maps the shared region using APRs 6 and 7, starting at 
virtual address 140000(8). It could in fact use APRs 5 and 6, 
beginning at virtual address 120000(8); or APRs 4 and 5, 
beginning at virtual address 100000(8). 

TASK B maps the shared region at the first available APR above the 
task code, using APRs 2 and 3, beginning at virtual address 
40000(8). It could use APRs 3 and 4, 4 and 5, 5 and 6, or 6 and 7 
as well. 

Task C maps the shared region using APRs 6 and 7, starting with 
virtual address 140000(8). There is no other possible way for 
task C to map the shared region because APR 6 is the first 
available APR. 

When you task-build a referencing task, you can specify which APR 
to use in mapping the region. If you do not specify an APR, the 
Task Builder selects the highest set of available APRs. When task 
A and task C were built, either the user did not specify an APR, 
or APR 6 was specified. When task B was built, the user specified 
APR 2. 

An absolute shared region has its virtual addresses fixed when it 
is task-built. All tasks which reference it must use those 
virtual addresses, and the corresponding APRs, to map to the 
region. Figure 7-2 shows another region, ABSOLU, and three 
referencing tasks A, B and C. The shared region ABSOLU was built 
to use virtual addresses 120000(8) through 147777(8) (6K words) 
with APRs 5 and 6. All referencing tasks must map to the region 
using these APRs. Therefore, task A and task B can both map to 
the region, since APRs 5 and 6 are available. Task C, on the 
other hand, cannot reference ABSOLU, since APR 5 is already used 
by its task code. 
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Figure 7-1 Tasks Using a Position Independent Shared Region 
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Figure 7-2 Tasks Using an Absolute Shared Region 
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Because of the added flexibility of a position independent region, 
i.e., any APR can be used to map the region, it might seem that 
there is no reason to ever use an absolute region with its 
attendant APR restrictions. However, there are coding 
restrictions for position independent regions which require the 
use of highly specialized coding techniques. Because of these 
restrictions, the decision to create a position independent or an 
absolute region is usually based on these coding restrictions 
rather than on flexibilty alone. 

In general, resident commons, containing data, are created 
position independent and resident libraries, containing code, are 
created absolute. 

Figure 7-3 shows the program development process for creating a 
shared region and a referencing task. Specific steps for each 
process are discussed later in this module. Compile and 
task-build the shared region separate from the referencing task, 
and before task-building the referencing task. 

Since it is not an executable task, certain task-build switches 
are used to create a task image with no header and no stack. An 
additional file, called a symbol definition file, is also created 
at task-build time. This file contains information about the 
symbols defined in the region which the Task Builder will use when 
it builds the referencing task to set up the linkage to the 
region. 

After task-building the shared region, task-build the referencing 
task. It can be written and compiled earlier, if desired. The 
name of the region is specified to the Task Builder so that it can 
access the symbol definition file and set up the linkage to the 
shared region. The shared region must be installed (causing it to 
be loaded into memory as well) before any referencing task is run. 



REFERENCES TO A SHARED REGION 

The following kinds of references are made to a shared region by a 
referencing task: 

• The task retrieves data from or stores data in a resident 
common. FORTRAN COMMON is used for this purpose. 

• Subroutine call to a subroutine defined in a shared 
region. 
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PROCEDURE FOR CREATING SHARED REGIONS AND REFERENCING TASKS 



Creating a Resident Common 

1. Code the shared region. Typically consists of a COMMON 
statement and DATA statements which allow you to 
initialize the COMMON. 

2. Choose position independent for a resident common. 

3. Compile the shared region. 

4. If not already done, create the common type partition. 

• Name must be the same as the name of the region. 

• Best done when the system is SYSGENed. 

• Use the SET PARTITION (SET/MAIN in MCR) command to 
create a partition. 

• Use the SET NOPARTITION (SET/NOMAIN in MCR) command to 
eliminate a partition. 

• Examples: 



>SET PARTITION :MYCOM/BASE : 7114/SIZE: 200/COMMON 

Creates the common type partition MYCOM with base 
physical address 711400(8) and size 20000(8) bytes, 
no other partition may use this space at the same 
time . 

>SET NOPARTITION :MYCOM 
Eliminates the partition MYCOM. 



NOTE 

Before you create or eliminate any partitions on 
your system, check with your system manager to 
find out what area of memory you may use. 
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5. Task-build the shared region. 

• Symbol definition file (.STB) required. 

• Build position independent and / SHAREABLE : COMMON . 
This causes the Task Builder to include the COMMON 
names in the .STB file so that references to them in 
the referencing task are properly resolved. The 
/SHAREABLE : LIBRARY switch used in task-building 
resident libraries causes the COMMON (Psect for MACRO) 
names to be omitted from the .STB file. This avoids 
task-builder errors in the case of unintentional 
duplication of Psect names. 

• Use required switches and options (see Table 7-2) . 

6. Install the shared region in the common type partition 
before running any referencing task. 

• Not required before task-building the referencing 
tasks . 

• Use the INSTALL (INS in MCR) command to install the 
region. 

This command also loads the region into memory. 
This is unlike an executable task, which is 
usually loaded into memory only when it is 
activated . 

• There is no command to remove a region. It is removed 
by either installing another region or eliminating the 
partition. 
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Figure 7-3 Program Development for Shared Regions 
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The required switches and options in Table 7-2 are needed for 
various reasons. No header or stack is needed because this is not 
an executable task. The referencing tasks each have their own 
header and stack. The symbol table definition file is needed to 
allow the Task Builder to link referencing tasks to the region. 
The partition name specifies the partition into which the region 
will be loaded. 

For an absolute region you must specify a base address. If you 
specify a nonzero length, that value is used as a maximum, for 
length checking. A task-builder error results if the length of 
the region is longer than the length specified. If you specify a 
length of 0, the region is set up with the size needed for the 
code, so long as it doesn't exceed the normal 32K word virtual 
addressing limit. 



Table 7-2 Required Switches and Options for Building 

a Shared Region 



Switch/Option 



in DCL (MCR) 


Effect 


Defaults 


Notes 


/NOHEADER 


No task 


/HEADER 




(/-HD) 


header 






/ SYMBOL_TABLE 


Create a 


No .STB 


Needed for 


(Specify third 


.STB file 


file 


task-building 


output file) 






referencing task 


STACK=0 


No space 


STACK=256 (10) 






for stack 


words 






in . TSK file 






PAR= 


Specify 


PAR=GEN 


Partition name 


par [ : base : len] 


partition 


If base and 


must be same as 




name (set 


length not 


name of the .TSK 




base virtual 


specified , 


and .STB files 




address - 


information 






required if 


taken from 


For PI regions, 




absolute; must 


partition on 


if specifying 




also specify 


the system 


base and len, use 




length, or 




base=0, length=0 




maximum) 




or max 
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Example 7-1 has the source code for a resident common COMWP and a 
referencing task COMGP. The following procedure is used to create 
the resident common: 

1. Code the shared region. 

See COMWP. FTN in Example 7-1. The following note is keyed 
to the example: 

©Create the FORTRAN named COMMON, MYDATA, and put data 
into the array I. 

2. Compile the shared region. 

> FORTRAN/LI ST COMWP 

3. If necessary, create the common type partition. 

We will make a partition COMWP, eight blocks = 1000(8) 
bytes long. If the partition TSTPAR already exists on 
your system, you may be able to eliminate it and then set 
up your partition. Be sure to check with your system 
manager before doing this and also be sure to put TSTPAR 
back when you are finished. 

! Check current partitions on the system 
>SHOW PARTITIONS 

! Record base address and length of TSTPAR and the type 

!of partition. Convert the values to blocks by 

Idropping the last 2 zeroes. (For example, base 

laddress 123400 (8) =1234 blocks, 

!length=20000(8) bytes = 200(8) blocks) 

! Eliminate the partition TSTPAR 

>SET NOPARTITION: TSTPAR 

! Create the partition COMWP 

>SET PARTITION:COMWP/BASE:1234/SIZE:10/COMMON 
I Check to see if this worked correctly 
>SHOW PARTITIONS 

Later, to eliminate the partition and to replace TSTPAR, 
use these commands: 

>SET NOPARTITION: COMWP 

>SET PARTITION : TSTPAR/BASE : 1234/SIZE : 200/TASK 
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4. Task-build the shared region. 

To build position independent: 

> L INK/OPTI ONS/MAP/SHAREABLE : COMMON/NOHEADER - 
->/SYMBOL_TABLE/CODE:PIC COMWP,LB: [ 1 , 1 ] FOROTS/LIB 
Option? STACK=0 
Option? PAR=COMWP 
Option? <RET> 

The /OPTIONS switch allows you to enter options. /MAP 
indicates that you want a map file. / SHAREABLE : COMMON 
indicates that Psect names are to be placed in the .STB 
file (required to reference with FORTRAN COMMON) . 
/NOHEADER indicates that no task header be included in the 
task image since this is not an executable task. 
/SYMBOL_TABLE indicates that a . STB file be created. 
(COMWP. STB). /CODE:PIC indicates a position independent 
region. STACK=0 indicates no stack space is needed since 
this is not an executable task. PAR=COMWP indicates the 
partition is COMWP. The Task Builder gets the length (for 
a maximum check) from the partition on the system. 

5. Install the region. 

>INSTALL COMWP 

Installs the region and also loads it into memory. 

Note that this is different from an executable task, 

which usually isn't loaded until it is requested. 
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BLOCK DATA COMWP 

C 

C File COMWP ♦ FTN 
C 

C Proa ram to create and initialize 3 resident common 
C 

C Task-build instructions* Must include /SHAREABLE* COMMON 
C and /NOHEADER switches? STACK~0 and PAR=COMWP options* 
C Must create *STB file* May be /CQDE*PIC or absolute 
C (the default)* OTS library NOT reouired* 
C 

O [COMMON /MYDATA/ 1(256) 
[DATA I /128*5y 128*10/ 
END 



PROGRAM COMGP 

C 

C File COMGP* FTN 
C 

C Task to read data from a static region and print it 
C out at TI** It uses a COMMON to reference the data* 
C 

C Task-build instructions* 
C 

C LINK/MAP/OPTION COMGP* LB* CI » 1 3F0R0TS/LIBRARY 

C Option? RESC0M*=C0MWP/R0 

C Option? <RET> 

C 

Q COMMON /MYDATA/ L(256) ! Common to reference 
C ! shared region 

C Loop through to display red ion? 8 numbers on a line 
DO 50 J 1*249*8 

WRITE (5*10) (L(K) yK™J? J+7) ! Write values 
10 FORMAT (' '>I2>7I8> 

50 CONTINUE 

CAL.L. £XXT" 
END 



Example 7-1 Resident Common Referenced with FORTRAN COMMON 

(Sheet 1 of 2) 
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Run Session 

>INS COMWP 
>RUN COMGP 

3 3 3 3 3 3 3 3 

3 3 3 3 3 3 3 3 



3 3 3 3 3 3 3 3 

6 6666666 
6 6 6 6 6 6 6 6 



Example 7-1 Resident Common Referenced with FORTRAN COMMON 

(Sheet 2 of 2) 
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Creating a Referencing Task 

1. Code the task, using the FORTRAN COMMON used in creating 
the region. 

2. Compile the task. 

3. Task-build the task. 

• Specify shared regions by using one of the following 
options: 

RESCOM=common name - for a user resident common. 
The .STB and . TSK files may be on any device and 
in any UFD, using normal defaults. 

Append /RO or /RW for read-only or read-write 
access. 

- COMMON=common name - for a system resident common. 
The .STB and .TSK files must be in LB: [1,1]. 

Append :R0 or :RW for read-only or read/write 
access. 

(Note that a colon (:) is used for COMMON and 
a slash (/) is used for RESCOM when appending the 
RO or RW switches.) 

4. After installing the shared region, install and/or run the 
task . 

If the shared region is to be a system shared region, the .STB 
file and the .TSK file should be placed in LB: [1,1]. Otherwise, 
they can reside on any device under any UFD, as long as both files 
are in the same UFD on the same device. 

Read-only or read/write access affects the way the access bits in 
the page descriptor registers (PDRs) in the APRs are set up. A 
memory protect violation occurs if a task attempts to write to a 
region when it has read-only access. 
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COMGP.FTN in Example 7-1 contains the source code for a task to 
reference the shared region COMWP. Use the following procedure to 
create the task: 

1. Code the task. 

See COMGP.FTN in Example 7-1. The following note is keyed 
to the example : 

Q The same FORTRAN named COMMON , MYDATA, is used here as 
in COMWP. FTN to set up referencing. 

2. Compile the task 

3. Task-build the task 

>LINK/OPTION/MAP COMGP 
Option? RESCOM=COMWP/RO 
Option? <RET> 

Link task to resident common COMWP. COMWP. TSK and 
CONWP.STB are in the current UFD on SY: . Set up 
read-only access. Use the highest available APR, APR 
7, if the region was built position independent. 

4. After installing the shared region, install and/or run the 
task. 

To do a temporary install, run, remove: 

>RUN COMGP 

To install and then run: 

>INSTALL COMGP 
>RUN COMGP 
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Accessing a Region for Read-Only or Read/Write 

Whether read-only or read/write access is required is usually 
straightforward. If a task moves data into the region or changes 
a value in the region, read-write access is required. If a task 
moves data out of the region or just reads values in the region, 
read-only access is required. 

However, when QIOs are issued and the buffer is in the shared 
region, the situation is more involved. Obviously, to do a read 
(e.g., from a terminal) into a buffer in the shared region 
requires write access. A write (e.g., to a terminal) from a 
buffer in the region should only require read access. However, 
because the Executive is designed for very fast, real-time 
applications, it does not check the function code for a QIO 
directive to see whether it is a read or a write. Instead it 
assumes the worst case - that all QIOs involving a buffer in a 
shared region are reads (from a peripheral device) into a buffer 
in the region, and that therefore all QIOs require read/write 
access . 

This condition causes an I/O error (IO.SPR) for illegal user 
buffer. This condition does not cause errors in the example 
because FORTRAN WRITES create the output string in a buffer within 
the referencing task area and the QIOs do the writes from the 
referencing task area. However, if you issue QIOs directly, the 
above problem can exist. 

One solution is to get read/write access to the shared region. 
Another solution is to move the data from the shared region to a 
buffer in the referencing task area and then use that buffer for 
the QIOs. A third solution is to build the task as a privileged 
task. Privileged tasks, similar to privileged terminals, are 
granted certain extra access to the system which nonpr ivileged 
tasks don't have. Some privileged tasks just gain these extra 
access rights, others map to the Executive as well. Normally, the 
Task Builder builds a task as a nonprivileged task. For a 
discussion of privileged tasks and how to task-build them, see 
Appendix D. 
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CREATING AND REFERENCING A SHARED LIBRARY 

Example 7-2 contains a shared library, LIB. MAC, and a referencing 
task USELIB.FTN. The program LIB. MAC and the associated comments 
are included to illustrate how a MACRO program can be called from 
a FORTRAN program. Some knowledge of MACRO-11 is required to have 
a full understanding of the example. The FORTRAN user need only 
know the order of the arguments in the CALL in order to use these 
subroutines. 



The shared library contains four simple arithmetic routines to 
add, subtract, multiply, and divide two numbers. They are all 
written to be reentrant and, in addition, they are written so that 
they can be called from a FORTRAN program with a standard FORTRAN 
subroutine call. 



INTEGER 0P1,0P2,ANS 
CALL AADD(0P1,0P2,ANS) 

The argument list is set up as follows: 

******************************* 

* R5 * C0UNT=3 * 
******************************* 

* address of 0P1 * 
******************************* 

* address of 0P2 * 
******************************* 

* address of ANS * 
******************************* 



word, word 
longword 
longword 
longword 



Note that subroutines written in FORTRAN cannot be included in a 
resident library because the code generated by FORTRAN is not 
reentrant. For additional information on the FORTRAN/MACRO- 11 
interface, see Appendix C. 
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Each subroutine saves and restores all of the registers, using the 
system library routine $SAVAL. The referencing task, USELIB, 
calls each of the subroutines once, using the operands 8(10) and 
2(10), and displays just the answers for the four operations. The 
following notes are keyed to Example 7-2. 

O Each subroutine entry point is defined _ with a global 
symbol . 

Q Each subroutine is in a Psect of the same name as the 
subroutine. In fact, the Psects are optional since the 
library is built /SHAREABLE: LIBRARY. The specified Psect 
names are not placed in the .STB file. 

For AADD and SUBB, move the first operand to R0, perform 
the operation in R0, then move the answer to the third 
operand for return to the caller. 

Q For MULL, use Rl instead of R0, so that the product is 
limited to just Rl (16 bits). If R0 were used instead, a 
32-bit product is returned (low-order 16 bits in Rl, 
high-order 16 bits in R0) . 

Q For DIVV, a 32-bit dividend is assumed in Rn and Rn+1, so 
here it is R2 and R3 (low-order 16 bits in R3, high-order 
16 bits in R2) . Therefore, the 16-bit operand is placed 
in R3 and the high-order word is cleared. The 16-bit 
quotient, returned in R2, is then moved into the third 
operand for return to the caller. 

Q Task-build instructions needed to tie the task to the 
library. 
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Task-Building the Shared Library and the Referencing Task 

The instructions for task-building the library and the referencing 
task are included in Example 7-2; however one point should be 
emphasized. 

When Task Building the library, you must use the 
/SHAREABLE : LIBRARY switch to avoid task-builder errors when 
building the referencing task. Whether the library is to be a 
system resident library or a user resident library is determined 
strictly by where the .STB and the . TSK file for the library 
reside. If they are in LB: [1,1], the library is a system resident 
library. If the .STB and .TSK files exist in other than LB: [1,1], 
the library is a user resident library. 

When task building a referencing task, the option (not switch) 
RESLIB=1 ibrary name or LIBR=library name must be used. If the 
option LIBR is used, the search for the library will be done only 
in UFD LB: [1,1]. If the option RESLIB is used, the search for the 
library will be done on the default device and UFD, or on the 
device and UFD specified with the library name; for example: 

>LINK/OPTIONS/MAP COMPG 

Option? RESLIB=DB2: [200,5] LIBA1/R0 

The above comments also apply to the creation and referencing of a 
common region. The only difference is that when the common is 
task-built, the /SHAREABLE: COMMON switch is generally used and 
when the common is referenced, the option COMMON=name is used for 
a system resident common, and RESCOM=name is used for a user 
resident library. 
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♦ F I TLE 

♦ I DENT 
♦ ENABL 



LIB 

/Ol/ 

LC 



9 Enable lower case 



? File LIB ♦ MAC 
y 

i This file contains the FORTRAN callable subroutines 

P AABD r SUBBy MULL. 9 and DIVV» which perform the 

? appropriate integer operation* 
5 

i Calling convention* CALL sub CopI ?op2?ans) 



Task-build instructions* Must include /SHAREABLE * LIBRARY 
and /NOHEADER switches? STACHX) and PAR*LIB options* 
Must create *STB file* Maw be /CODE ♦ PIC or absolute 
(default)* Usir..s= /SHAREABLE * LIBRARY avoids Psect 
corif I icts ♦ 



© 

AADD * * 



♦ PSECT 
CALL 
MOV 
ADD 
LMOV 
RETURN 



AADDyROy I ?GBL 
*SAVAL 
02 (R5) 9RO 
(?4<R5) yRO 
R0y@6(R5) 



REL y CON 

9 Save all registers 

9 Move 1st operand 

9 Add 2nd operand 

9 Store result 

9 Restore re£s and return 



If ♦ PSECT SUBB y RO y I y GBL 9 REL 

subbj: call $saval $ 

MOV G?2(R5)yR0 9 

SUB @4(R5)yR0 y 

LMOV R0y@6<R5) y 

RETURN y 



CON 

Save all registers 
Move 1st* operand 
Subtract 2nd operand 
Store result 
Restore re3s and return 



MULL ♦ ♦ 



♦PSECT 
CALL 
MOV 
MUL 

LMOV 
RETURN 

♦ PSECT 
C AL. L. 

rMov 

CLR 
DIV 
LMOV 
RETURN 
* END 



MULLyROy I yGBL 
*SAVAL 
@2<R5> yRl 
@4<R5> yR.l 

Rl ?@6<R3) 



REL y CON 
y Save 



all registers 
Move 1st operand 
Mul t i p I w < answer 'i n 

Just Rl) 
Store result 
Restore resJs and return 



DI W 9 RO y I y GBL y REL 9 CON 



*SAVAL 

@2<R5> yR3 
R2 

@4<R5) »R2 
R2»@6<R5> 



y Save all registers 

y Move 1st operand 

y Clear hisJh order 16 bits 

y Divide 

y Store result 

y Restore re«$s and return 



Example 7-2 Shared Library (Sheet 1 of 2) 
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PROGRAM USELIB 

C 

C File USELIB *FTN 
C 

C FORTRAN t3sk to use resident library LIB 
C 

C Task-build instructions* 
C 

c >link/code:fpp/map/option uselib»lb:ci>i3'for- 

C Q ->OTS/LIBRARY 

C w Option? RESLIB-LIB/RO 

C Option? <RET> 

C 

INTEGER ANS»0P1>0P2 



DATA 


0Ply0P2 


/8?2/ 






CALL. 
TYPE 


AADD(OPl 
lOOy ANS 


y 0P2 9 


ANS) 


! Add operands 
! Print results 


C AL~ L. 
TYPE 


SUBBCOP1 
100? ANS 


9 0P2 9 


ANS) 


! Subtract operands 
! Print results 


C A L. L. 
TYPE 


MULL (OP 1 
100? ANS 


9 0P2 9 


ANS) 


! Multiply operands 
! Print results 


CALL 
TYPE 


DIWC0P1 
100y ANS 


yOP2y 


ANS) 


! Divide operands 
! Print results 


CALL 


EXIT 









c 

100 FORMAT C THE ANSWER « '»I2>'*'> 

END 



Run Session 



>INS LIB 
>RUN USELIB 
THE ANSWER IS 10. 
THE ANSWER IS 6* 
THE ANSWER IS 16 ♦ 
THE ANSWER IS 4* 



Figure 7-2 Shared Library (Sheet 2 of 2) 
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DEVICE COMMONS 

A device common is a special type of common that occupies physical 
addresses on the I/O page. The I/O page does not contain physical 
memory, but peripheral device registers instead. Therefore, a 
device common does not contain data the way a regular resident 
common does. It is really just a way of setting up addressing to 
allow a task to manipulate the device registers directly. This 
might be useful in checking out the proper commands needed to 
control a device or to check what control status registers (CSRs) 
are in use on your system. Obviously, extreme care must be used 
if you manipulate a device which is also referenced by any system 
routines (e.g., a system device driver). 

Privileged tasks which map to the Executive can also automatically 
map the I/O page. However, privileged tasks must be written very 
carefully to avoid causing additional problems for the running 
system. Device Commons allow nonpr ivileged tasks to manipulate 
device registers. 

While a device common region can be created in FORTRAN, by its 
nature, referencing must be done via MACRO-11. For an example see 
the RSX-11M/M PLUS Task Builder Manual . 

Appendix F contains information about more advanced shared region 
topics. It includes a discussion of the following topics: 

• Overlaid shared regions 

• Referencing several shared regions from one referencing 
task 

• Handling interlibrary calls 

• Cluster libraries 

Most of the techniques discussed are more appropriate for the 
MACRO-11 programmer who is running into virtual address limitation 
problems. Cluster libraries are designed to save virtual address 
space in tasks which use DIGITAL layered products, such as 
FORTRAN, FMS (Forms Management Services) , and FCS (File Control 
Services) . If you write FORTRAN programs which use these 
products, you may find it useful to just read the last few pages, 
which cover the procedure for task-building a task which 
references two or more DIGITAL supplied resident libraries as a 
set of cluster libraries. 
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Now do the Tests/Exercises for this module in the Tests and 
Exercises Book. They are all lab problems. Check your answers 
against the solutions provided, either the on-line file (under UFD 
[202,2]) or the hard copy in the Tests and Exercises Book. 

If you feel that you have mastered the material, have your course 
administrator record your progress on your progress plotter. You 
will then be ready to begin a new module. 

If you feel that you have not yet mastered the material, return to 
the module for further study. 



258 



DYNAMIC REGIONS 



DYNAMIC REGIONS 



INTRODUCTION 

The last module discussed how to use the Task Builder to create 
and access static regions. It is also possible to create and 
access regions while a task is executing. Such regions are called 
dynamic regions. The memory management directives allow a task to 
create and access dynamic regions and access existing static 
regions. In addition, they offer a facility for creating private 
regions and for allowing other tasks to access these regions. 



OBJECTIVES 

1. To write tasks which create a dynamic region and access 
dynamic and/or static regions 

2. To write tasks which dynamically control their mapping 

3. To write tasks which create a private dynamic region and 
allow one or more other tasks to access the region. 



RESOURCE 

• RSX-11M/M-PLUS Executive Reference Manual , Chapter 3 plus 
specific directives in Chapter 5 
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SYSTEM FACILITIES 

Sometimes a task's needs for memory and for shared regions aren't 
known until run time, or the needs may change at run time. 
Examples are: 

1. A task, e.g. an editor, needs a temporary work buffer for 
only part of the time the task is active. 

2. A task needs a shared region or work buffer, but its size 
depends upon the needs of the user running the task (e.g., 
the size of an input file) . 

3. A task creates a shared region and wants to control access 
to it by other tasks. 

4. A task wants to create a shared region in a system 
controlled partition (e.g., GEN) instead of in a dedicated 
common type partition. Then when the shared region isn't 
needed, the space automatically is available for other 
system needs (tasks, etc.). 

5. A task needs to map to two different shared regions at 
different times, but has only one 4K word virtual address 
window available. 

Special directives, called memory management directives, are 
available on mapped systems to allow tasks to perform the 
following functions: 

• Create regions in system controlled partitions 

• Attach/detach from a region 

• Create/eliminate virtual address windows 

• Map/unmap a virtual address window to an attached region 

• Obtain information about its mapping from the system 

The memory management directives are a SYSGEN option. Therefore, 

if users on a system plan to use them, they must be included in 

the Executive at SYSGEN time. Check with your system manager to 
find out if they have been included on your system. 
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Table 8-1 lists the memory management directives which are 
available on an RSX-11M system. 

Table 8-1 Memory Management Directives 



Function 


FORTRAN Calls 


Attach region 


ATRG 


Create address window 


CRAW 


Create region 


CRRG 


Detach region 


DTRG 


Eliminate address window 


ELAW 


Get mapping context 


GMCX 


Map address window 


MAP 


Receive-by- reference 


RREF 


Send-by-ref erence 


SREF 


Unmap address window 


UNMAP 
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REQUIRED DATA STRUCTURES 

Each memory management directive requires that you set up one of 
two data structures within your task; namely a region definition 
block (RDB) or a window definition block (WDB) . The RDB and the 
WDB are the interface between the user task and the Executive. 
Their contents change dynamically as regions are created and 
accessed. In general, once the WDB and/or the RDB are set up, the 
actual memory management directive FORTRAN calls are quite 
straightforward. Their format is either: 

CALL XXXX(wdb,idsw) 
or 

CALL XXX(rdb,idsw) 

where wdb is the name of an 8 word integer array 
for the Window Descriptor Block 

rdb is the name of an 8 word integer array 
for the Region Descriptor Block 

Examples: 

INTEGER WDB ( 8 ) f RDB ( 8 ) 
. . . 

. . . 

CALL CRAW (WDB, IDSW) 
CALL CRRG (RDB, IDSW) 



Region Definition Block (RDB) 

An RDB contains information needed to create a region and/or to 

attach to a region in a system controlled partition. The RDB is 
used by the following directives: 

• Attach Region (ATRG) 

• Create Region (CRRG) 

• Detach Region (DTRG) 
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Figure 8-1 shows the arguments for the various RDB elements. The 
meaning of the elements is as follows: 

Region ID - a unique number assigned to a region when your 
task attaches to a region. The number associates the task 
with the region. It is returned by the Executive after 
your task attaches to a region. 

Size of Region - the size of a region to be created, in 
32-word blocks. Also used to return a size when attaching 
an existing region. 

Name of Region - up to six characters in Radix-50. 
Assigned when a region is created and used when attaching 
to a region. 

Region's Main Partition Name - up to six characters in 
Radix-50. The name of the system controlled partition. 

Region Status Word - used by the user task to send 
information to the Executive when creating or attaching to 
a region. Also used by the Executive to return status to 
the task after a memory management directive is executed. 
Table 8-1 lists the various bits and their meanings. 

Region Protection Word - Analogous to the file protection 
word, controlling access to regions. As shown below, it 
is set up with the same format (RWED for Read, Write, 
Extend, Delete) within each category: System, Owner, 
Group, and World: 



World Group Owner System 

DEWR DEWR DEWR DEWR 

1110 1110 0000 0000 = 167000(8) 

A 1 means access is denied, a means access is permitted. 
The example means world and group have read access; owner 
and system have all access. 
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ARRAY 

ELEMENT ARGUMENTS 



irdb (1) 



irdb (2) 
irdb (3) 
irdb (4) 
irdb (5) 
irdb (6) 
irdb (7) 
irdb (8) 



BLOCK FORMAT 



siz 



nam 



par 



sts 



pro 



REGION ID 



SIZE OF REGION (32W BLOCKS) 



NAME OF REGION (RAD50) 



REGION'S MAIN PARTITION NAME (RAD50) — 



REGION STATUS WORD 



REGION PROTECTION WORD 



Figure 8-1 The Region Definition Block 
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Table 8-2 Region Status Word 



Octal 

Symbol Value Set By Definition 



RS.CRR 100000 System Region successfully created 

RS.UNM 40000 System At least one window unmapped on a 

detach 

RS.MDL 200 User Mark region for deletion on last 

detach 

RS.NDL 100 User Created region not deleted on last 

detach 

RS.ATT 40 User Attach to created region 

RS.NEX 20 User Created region not extendable 

RS.DEL 10 User Delete access desired on attach 

RS.EXT 4 User Extend access desired on attach 

RS.WRT 2 User Write access desired on attach 

RS.RED 1 User Read access desired on attach 



Just as in other modules, the symbols shown are those used in the 
documentation and by MACRO programmers. The symbols can be 
converted to FORTRAN acceptable variable names by dropping the 
period in the symbol. Values may be assigned by using the DATA 
statement. 
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Creating an RDB in FORTRAN 

Example : 

Create an RDB for a region with the following specifications: 
Size in 32(10) word blocks = 2 
Region name = MYREG 
Partition name = GEN 
Region to be attached on create 
Region to be marked for delete on last detach 
Write access desired on attach 

Owner to have all privileges and group to have read privileges 
DIMENSION IRDB(8) 



DATA IRDB/0, 2,3RMYR,3REG , 3RGEN , 3R 242 , " 177017/ 

In the above, the region status word (word 7 = 242(8)), is the sum 
of 200(8) + 40(8) +2(8). See table 8-2 for meanings. 

The region protection word is 177017(8), which breaks down as 



follows : 



World 

DEWR 

1111 



Group 

DEWR 

1110 



Owner 

DEWR 

0000 



System 

DEWR 

1111 
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Example: 

Create an RDB for a region with the following specifications: 
Size in 32(10) word blocks = 1000(8) 
Region name = XXXX 

Partition name = same as task is installed in 

Region status = do not delete, desired access to be filled in 
before attaching 

World to have no privileges, all others to have all privileges 

DIMENSION IRDB(8) 
. • • 

DATA* IRDB/0,"i000,3RXXX,3RX , , ," 1 00 ," 170000/ 

Note that any value the Region Descriptor Block could be changed 
dynamically at run time by using input values to change various 
parts of the RDB. 

Window Definition Block (WDB) 

A WDB contains information needed to create a virtual address 
region and to map a virtual address window to an attached region. 
The WDB is required for the following directives: 

• Create Address Window (CRAW) 

• Eliminate Address Window (ELAW) 

• Map Address Window (MAP) 

• Unmap Address Window (UNMAP) 

• Send-by-Ref erence (SREF) 

• Receive-by-Ref erence (RREF) 
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Figure 8-2 shows the layout of the WDB. 

The meaning of the elements is as follows: 

Window ID - A number which identifies the window block in 
the task header which describes the window. Window is 
used for the task window. Windows 1 through 7 are used 
for additional windows set up by the Task Builder for 
overlays and static regions and for windows created 
dynamically. The window ID is returned by the Executive 
after a Create Address Window directive. The Task Builder 
option WINDWS=n must be used to specify the number of 
additional window blocks needed for dynamic windows. 

Base APR - The base APR to be used in mapping the window, 
which sets the base virtual address. 

Base Virtual Address — The base virtual address in octal; 
returned by the Executive after a Create Address Window 
directive. 

Region ID - The region ID, used to identify the region 
when mapping a virtual address window to a region; 
returned by the Executive in the RDB after an Attach 
Region directive. You must move the value returned from 
the RDB to the WDB before mapping to the region. 

Offset in Region (32 word blocks) - The offset within the 
region at which mapping is to begin. Allows a task to map 
to different portions of a region. 

Length to Map (32-word block) - The length within the 
region to be mapped. Defaults to the shorter of the space 
remaining in the region and the size of the window. 

Window Status Word - Used by the user task to send 
information to the Executive when creating and mapping 
windows. Also used by the Executive to return status to 
the user task after a directive is executed. Table 8-3 
lists the various bits and their meanings. 

Send/receive buffer address - The address of an eight-word 
buffer for sending or receiving data as part of the 
Send-by-Ref erence and Receive-by-Ref erence directives. 
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ARRAY 

ELEMENT ARGUMENTS 



iwdb (1) 
iwdb (2) 
iwdb (3) 
iwdb (4) 
iwdb (5) 
iwdb (6) 

iwdb (7) 
iwdb (8) 



apr 

siz 
rid 
off 
len 
sts 
srb 



BLOCK FORMAT 



BASE APR 



WINDOW ID 



VIRTUAL BASE ADDRESS (BYTES) 



WINDOW SIZE (32W BLOCKS) 



REGION ID 



OFFSET IN REGION (32W BLOCKS) 



LENGTH TO MAP (32W BLOCKS) 



WINDOW STATUS WORD 



SEND/RECEIVE BUFFER ADDRESS 



Figure 8-2 The Window Definition Block 
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Creating a WDB in FORTRAN 

Example: 

Create a WDB to describe a window with the following: 
APR = 7 

Size in 32(10) word blocks = 100(10) 

Region to be mapped in a CALL CRAW or CALL RREF directive 
Map with read access 
Map 100(10) blocks 

DIMENSION IWDB(8) 

DATA IWDB/"3400 f 0,100, 0,0, 100," 201,0/ 



Note that the APR number (7 in the example) must be placed in the 
high byte of the first word in the WDB. This can be done by 
putting 3400(8) into IWDB(l). 3400(8) is 00000111 00000000(2) 
which puts a 7 in the high byte for the base APR. This can also 
be done by setting IDWB ( 1 ) =7*256 . 

Word 7 (201(8)) is the window status word. See Table 8-3 for the 
definitions of the bits in this word. 



Create a WDB to describe a window with the following: 
APR = 5 

Size in 32(10) word blocks = 200(8) 

Map starting at offset of 5 blocks in region and map 
10(10) blocks 

Send with delete! and write access 
DIMENSION IWDB(8) 



DATA IWDB/" 2400, 0,200, 0,5, 10," 412,0/ 
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Table 8-3 Window Status Word 



Symbol 


Octal 
Value 


Set By 


Definition 


WS.CRW 


100000 


System 


Address window successfully 
created 


WS . UNM 


40000 


System 


At least one window unmapped by 
a CRAW, MAP or UMAP directive 


WS.ELW 


20000 


System 


At least one window eliminated 
in a CRAW or ELAW directive 


WS . RRF 


10000 


System 


Reference successfully received 


WS.64B 


400 


User 


Defines permitted alignment for 
offset start within the region 

for 256-word alignment (8 blocks) 

1 for 32-word alignment (1 block) 


WS.MAP 


200 


User 


Window to be mapped in a CRAW or 
RREF directive 


WS.RCX 


100 


User 


Exit if no references 


WS.DEL 


10 


User 


Send with delete access 


WS.EXT 


4 


User 


Send with extend access 


WS.WRT 


2 


User 


Send or map with write access 


WS.RED 


1 


User 


Send with read access (map is 
with read access by default) 
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CREATING AND ACCESSING A REGION 

Use the following procedure to create and access a region: 

1. Create the region (Create Region directive) 

2. Attach to the region (Attach Region directive) 

3. Move the region ID from the RDB to the WDB 

4. Create a virtual address window (Create Address Window 
directive) 

5. Map the virtual address window to the region (Map Address 
Window directive) 

6. Use the region 

7. Detach from the region (Detach Region directive or task 
exit). It is recommended that a task always issue the 
Detach Region directive rather than depend on the EXIT 
processing code to issue the Detach. The reason for this 
is that if a task is fixed and EXITs, then no detach is 
done. If you run the fixed task over and over, you could 
run out of pool. 

Steps 1 and 2 and also steps 4 and 5 can each be combined in a 
single directive call. Step 4 can be performed earlier, if 
desired. To access an existing region, begin with step 2. 

If you don't remember what windows and regions are and also what 
attaching and mapping mean, look over the sections on Windows and 
Regions in the last few pages of Module 5, the Memory Management 
module. 

The use of each directive in the procedure above is detailed on 
the following pages. The discussion includes: the purpose of the 
directive, important input and output parameters, plus notes about 
its use. For a complete discussion of each directive, see Chapter 
5 of the RSX-11M/M-PLUS Executive Reference Manual . For 
additional information on the memory management directives, see 
Chapter 3 of the same manual. 
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Creating a Region 

When you create a region, the Executive allocates space for it in 
a system controlled partition. Use the Create Region directive 
(CRRG) with the following RDB input parameters: 

1. Size of region (in 32(10) word blocks) 

2. Name of region (becomes a private region if no name) 

3. Name of partition (defaults to partition of task) 

4. Region Status Word - mark for delete or do not delete 
(default is mark for delete) 

5. Region protection word - determines permissible access to 
region 

In the following discussion, the MACRO symbols are used for the 
various Window Status Word bits. See Table 8-3 (Window Status 
Word) for definitions and values. 

The only RDB output parameter is the RS.CRR bit in the region 
status word. It is set if the region is successfully created, and 
cleared if not. Normal Executive directive status is returned as 
well (carry set for error, clear for success; DSW contains 
directive status word). If the region already exists, success 
status is returned. Therefore, RS.CRR can be used to tell whether 
the region was in fact created or whether it already existed. The 
following code segment illustrates how to examine RS.CPR to see if 
the the region was successfully created. 

INTEGER RSCPR,RDB(8) 
DATA RSCPR/"100000/ 

• • 

I=RDB(7) .AND. "100000 

Now test I. If I is 0, the region was not created; otherwise it 
was. 
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Any task which passes the protection test can attach to a named 
region. For unnamed (private) regions, only tasks which are 
specifically attached by the creator of the region may attach to 
it. Therefore, for a private region, the creator completely 
controls which tasks attach to it, and their access rights as 
well. 

By default, or if RS.MDL is set in the region status word, the 
region is deleted when the last attached task detaches from the 
region. Named regions are left in existence after the last detach 
if RS.NDL is set in the region status word when the region is 
created. Unnamed (private) regions are always marked for delete 
(deleted on last detach) . There is no explicit Delete Region 
directive . 

If the RS. ATT bit is set in the region status word, the Executive 
also attempts to attach the task to the region. In this case, 
additional RDB input parameters are required and additional output 
parameters are returned. Attaching to a region is discussed after 
Example 8-1. 

Example 8-1 shows how to create a named region which is left in 
existence on the last detach. The following notes are keyed to 
the example. 

Set up the RDB. RS . NDL ( 100 (8 ) ) in the region status word 
(RDB ( 7 ) ) specifies that the region is to be left in 
existence. 



Region Protection Word = 



World 

DEWR 

1111 



Group 

DEWR 

0000 



Owner System 
DEWR DEWR 
0000 0000(2) 



170000 (8) 



Bit set means access denied 



e 



Issue directive to create region, specifying the RDB 
address and the DSW as the only arguments. 



e 
o 



Check for directive error. 



Display message and exit. 
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PROGRAM CRERG 

C 

C File CRERG *FTN 
C 

C CRERG creates a named region and exits* leaving the 

C region in existence* 

C 

C RDB ~ Region Definition Block for region with the 
C following properties* 

C Size ~ 100 (32* word blocks) 

C N3me * MYREG 

C Partition = GEN 

C Protection ~ U0 ♦ None r SY ♦ RUED 

C OU * RUED 9 GR ♦ RUED 

C Do not mark for delete on last detach 

C 

INTEGER RDB (8) 
C Initialize the RDB 

£k DATA RDB/Oy 8 100 y 3RMYR » 3REG *3RGENy3R ? 

w l-000100y "170000/ 
C Create region 

CALL CRRG(RDBvIDS) 
C Branch on error 

IF(IDS»LT»0)G0T0 800 
C Urite success message 
URITE <5*15) 

15 O FORMAT <' CRERG SUCCESSFULLY CREATED MYREG') 
C Go to common exit 

GOTO 1000 
C Urite create error message 
800 URITE (5* 850) IDS 

850 FORMAT (' ERROR IN CREATING REGION y DSU * '»I4> 

1000 CALL EXIT 
END 



Run Session 
>RUN CRERG 

CRERG SUCCESSFULLY CREATED MYREG 



Example 8-1 Creating a Region 



\ 
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Attaching to a Region 

When you attach your task to a region, the Executive creates a 
logical connection between the two. The region can be either a 
dynamic region or a static region. Use the Attach Region 
directive (ATRG) with the following RDB input parameters: 

Region name 

Region Status Word (indicating R,W,E,D access) 

The following RDB output parameters are returned: 

Region ID 
Region size 

The region ID is needed later in order to map a virtual address 
window to the region. The region size is of interest when 
attaching to an already existing region whose size may not be 
known. 

Attaching can also be done as part of the Create Region directive 
(CRRG) , if the RS. ATT bit in the region status word is set when 
the Create Region directive is issued. In fact, for an unnamed 
region, attaching must be done as part of the Create Region 
directive, since there is no region name to be used in a separate 
Attach Region directive. 

A task can detach from a region by using an explicit Detach Region 
directive (DTRG) or by exiting (the Executive detaches the task) . 
If a task is changing a region from "do not delete" to "mark for 
delete", an explicit detach is required with RS.MDL set in the 
region status word. If a task exits without issuing an explicit 
detach, and the task is not fixed, the Executive detaches the task 
but does not mark the region for delete. Once a region is marked 
for delete, it is deleted when the last attached task detaches 
from it. Once it is marked for delete it cannot be changed to "do 
not delete". 

If a fixed task exits without issuing a detach, no detach is 
issued by the Executive. 
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Creating a Virtual Address Window 

When you create a virtual address window for a task, the Executive 
initializes a window block in the task header. It also checks to 
ensure that this is the only window that uses the specified range 
of virtual addresses, unmapping and eliminating any window that 
overlaps that range. Use the Create Address Window directive 
(CRAW) with the following WDB input parameters: 

Base APR number 

Window size (in 32(10) word blocks) 

The following WDB output parameters are returned: 

Window ID assigned by the system (1-7) 
Base virtual address 

The space for the additional window blocks in the task header must 
be reserved at task-build time using the WNDWS=n option. N is the 
number of additional windows needed for windows created at run 
time. If extra space is not allocated, an address window 
allocation overflow error (IE.WOV= -85.) results when you attempt 
to create a virtual address window. 

The window is also mapped to a region if bit WS.MAP is set in the 
window status word when the Create Address Window directive is 
issued. In that case, additional input parameters are needed. 
See the following section on Mapping to a region. 

The Eliminate Address Window (ELAW) directive can be used to 
explicitly eliminate a virtual address window. In general, it is 
not used because creating a new window automatically eliminates 
any overlapping window. 
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Mapping to a Region 

When you map a virtual address window to a region, the Executive 
creates a logical connection between the virtual address window 
and the region. Any attached region can be mapped. In the 
process, the memory management registers are loaded so that 
references to virtual addresses in the window access the region. 
This assumes, of course, that the task keeps control of the CPU. 
The APRs are reloaded every time a new task takes control of the 
CPU. 

Use the Map Address Window directive (MAP) to map a window to a 
region, with the following WDB input parameters: 

Region ID - Returned to RDB by Attach (move from RDB to 
WDB) . 

Offset into Region - in 32-word blocks, used to start 
mapping at an offset from the start of the region. This 
must be a multiple of 8(10) unless WS.64B is set in the 
window status word. If WS.64B is set, any whole number 
may be specified. 

Length to Map - If specified, must be less than or equal 
to shorter of length of window and length remaining in 
region. If defaulted, is set to the shorter of the two. 

Window status word - actual access desired (read-only, or 
read/write) . Read access is always requested by default 
so a request for write access actually requests read/write 
access, and a request for no access actually requests read 
access. 

The only WDB output parameter generally used is the length 
actually mapped. If the window is already mapped, it is first 
unmapped by the Executive. You can also use the Unmap Address 
Window directive to explicitly unmap a window. Mapping can also 
be done as part of the Create Address Window directive (CRAW) . 

The access desired is used here in addition to that declared when 
attaching because several windows in the task may map the same 
region. Some of the windows may need read-only access, others may 
need read/write access. In that case, you must attach with 
read/write access, and then you may map each window with either 
read-only access or read/write access. 
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Example 8-2 shows how to create a region and place data into 
it, leaving it in existence on exit. Example 8-3 shows how to 
attach to that region, read and display the data, and finally 
detach and mark it for delete. One run session covers both 
examples. The following notes are keyed to Example 8-2. 



Task-building with the WNDWS=1 option causes the Task 
Builder to allocate space in the task header for one 
additional window block. You must also use the VSECT 
option to create a virtual section starting at 160000(8) 
for an extent of 20000(8). APR 7 must be used to map the 
section because the section's beginning address is 
160000(8). The name of the virtual section is DATA. This 
ties the FORTRAN named COMMON DATA to the virtual section. 

Q RDB for region. Note that RDB ( 7 ) , the region status word, 
is 152(8). This is the combination of the following: 



RS.NDL = 100 (8) 

RS.ATT = 40(8) 

RS.DEL = 10(8) 

RS.WRT = 2(8) 



152(8) 

See Table 8-1 for the above definitions. 

O WDB for virtual address window. The third argument is for 
the region ID, which will be filled in at run time after 
the task attaches to the region. In the window status 
word, WS.MAP (200(8)) means that the Create Address Window 
directive will both create the window and map it to the 
region. WS.RED (1(8)) is automatic, even though not 
specified. WS.WRT (2(8)) indicates to map with write 
access. The sum of the two needed octal codes is 202(8). 

Q Create region and attach. 

Q Move region ID, returned in RDB ( 1 ) after attach, into 
WDB(4) for mapping. 

O Create a virtual address window and map it to the region. 

The virtual address window begins with APR 7, so the base 

address in the window is 160000(8), corresponding to the 
base address in the region. 
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Place a byte count, 400(10), in the first word in the 
region. This is just one way to communicate this 
information to other tasks which access the region. The 
length of the region is returned when a task attaches to 
the region. You could use this as an alternate way to 
pass the information about the amount of data. 

Move 100(10) words of ASCII "AB" and 100(10) words of 
ASCII "12" into the region. This gives us 200(10) words 
or 400(10) bytes of data. 

Display a successful creation and initialization message 
at the terminal. 

Detach from the region and then exit, leaving the region 
in existence. 
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PROGRAM CREURG 
File CREURG ♦ FTN 

CREURG creates 3 named region (attached on creation) y 
creates a virtual address window (.mapped on creation) y 
places ASCII data in the regiony detaches from the 
region and exits y leaving the region in existence* 
It places a count word in the first word of the 
region y telling how many bwtes of data follow* 

T a s k - h u i 1 d i n s t r u c t i o n s i 

>L INK/MAP/OPT IONS/CODE * FPP CREURG y LB t L" 1 y 1 HFORDTS- 
->/LIBRARY 

Option? v"SECT~DATA ♦ .1.60000*20000 
Option? WNDWS*1 
Option? <RET> 



RDB ~ Region Definition 
following properties? 
"Size 
Name 

Partition 
Protection 



Block for region with the 



(3: 



word blocks) 



Do not 
.Attach 



mark 
with 



for 



= 100(8) 
= MYREG 
« GEN 

* W0 ♦ None y S Y * RUED 
0U * RUED y GR * RUED 
delete on last detach 



write and delete access 



UDB 



Uindow Definition Block for window with the 



following 
APR 



properties* 



Size 

Offset in 
Length in 



region 
region 



lOOoctal (32* word blocks) 
(32* word blocks) 
lOOoctal (32* word blocks) 



Map on create with write access 



INTEGER RDB(8) yUDB(8) 

COMMON /DATA/ IDATA(201) 
Initialize the RDB 

DATA RDB/Oy " 100 y 3RMYR y 3REG y3RGENy3R 
Initialize the UDB 

O DATA UDB/"3400y0y "lOOyOyOy "100y "202y 
Call routine to create and 3ttach region 

CALL CRRG(RDBylDS) 
Check for error 

1T(IDS*LT,0)G0T0 800 
Create address window 3nd map to region 

WDB<4)aRDB.(l) 

CALL CRAU(UDBylDS) 



y " 000 J. 52 y "170000/ 



0/ 



Example 8-2 Creating a Region and Placing 
Data in It (Sheet 1 of 2) 
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C Check for error 

IF(IDS.LT*0)GOTO 810 
C PI ace data in region 1st word is a byte count 
Q IDATA<1)=400 
r00 10 J=*2yl01 
10 fk IDATA< J)~'AB' 

W DO 20 K=-"102?201 
20 LlDATA<K)~-= , 12' 
C Detach from region 

Q CALL DTRG(RDBvIDS) 
C Check for error 

IF< IDS *LT*0) GOTO 820 
C Write message 

TYPE *y 'CREURG HAS CREATED AND INITIALIZED THE 
1 REG I ON ' 
C Branch to common exit 

GOTO 1000 
C Write create error message 
t300 WRITE<5y805)IDS 

BOS FORMAT ( ' ERROR IN CREATING REGION y DSW ~ 'y.I4> 

C Go to common exit 

GO TO 1000 
Write attach error message 
BIO WRITE(5y815)IDS 

815 FORMAT < ' ERROR IN CREATING WINDOW AND MAPPING y 

1DSW = ' yI4) 

GOTO 1000 
C Write detach error message 
820 WRITE(5y825)IDS 

825 FORMAT ( ' ERROR IN DETACHING FROM REGIONy DSW = 

ly.I4) 
C Common exit 
1000 CALL EXIT 

FNin 



Run Session 
>RUN CREURG 

CREURG HAS CREATED AND INITIALIZED THE REGION 
>RUN ATTURG 

ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB 
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB 
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB 
ABABABAB1212121212121 2121212121212121212121212121212121212121212 
:l.21212121212121212121212121212121212121212121212121212121 2121212 
1212121212121212121212121212121212121212121212121212121212121212 
.1.212121212121212 



Example 8-2 Creating a Region and Placing 
Data in It (Sheet 2 of 2) 
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The following notes are keyed to Example 8-3. 

Q Again, task-build with the WNDWS=1 option so the Task 
Builder allocates space for the window block in the task 
header and with the VSECT option. 

O The RDB for attaching to the region. The only required 
information is the region name and the region status word. 
The partition name and the size, although included, are 
not required. RS.MDL (200(8)) (set) marks the region for 
delete when we do an explicit detach. We need delete 
access to mark the region for delete (RS.DEL=10 (8) ) . In 
addition, attach with read (RS.RED=1 (8) ) and write 
(RS.WRT=2 (8) ) access so we can map with read/write access. 
The sum of the region status codes above is 213(8). 

The WDB for the virtual address window. We map the entire 
region (length = 100 (8) 32-word blocks) starting from the 
beginning (offset = 0). WS.MAP means create the address 
window and map. Map with read (WS.RED) and write (WS.WRT) 
access. The sum of the window status codes is 203(8). 

Q Attach to the region. 

O Move the region ID to the WDB and create the virtual 
address window and map it to the region. 

Q First word in the region contains a character or byte 
count. Convert it to a word count. 

Print the contents of the region, 64(10) characters per 
line. This technique is used to demonstrate how to 
control the width of the output and to make the run 
session fit on an 8 1/2 by 11 inch page with margins. If 
the full terminal buffer width (typically 80(10) or 
132(10)) is acceptable, the FORMAT could be 39A2 or 65A2. 

Q Detach from the region. Explicit detach required to mark 
the region for delete. 
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PROGRAM ATTURG 
File ATTURG ♦ FTN 

FORTRAN program to attach the existing region MYREG? 
create a virtual address window (mapped on creation) v 
read ASCII d3ta out of the region? detach from the 
region* and exit* The region is marked for delete 
arid will be deleted on last detach* 

The first word in the region contains a count of how 
many bytes of data are in the region* 

Task-build with these options* 

ft [VSECT=REGI0Nil60000J20000 
W [WNBUS=1 



INTEGER 
INTEGER 



RDB (8) *WDB(8) 
IDATA(2048) 



Th i s 



! Array for addressing 
! region (Full 4KW) 
with the address window 



RUB 



common block will align 

COMMON /REG ION/ I DATA 
: Region definition block with the following properties* 
Size (32*~word blocks) ~ returned 

when attached 

Name MYREG 
Partition GEN 
Mark for delete on last detach 
Attach with delete? read and write access 
Initialize the RDB 

DATA RDB /0 * > 3RM YR 9 3REG 9 3RGEN » 3R 9 "000213 
1?0/ 

WDB = Window definition block with the following properties* 
APR 7 

Size 200 octal (32*-word blocks) 

Offset in region (32* -word blocks) 

Length of window octal (32* -word blocks) ~ 

defaults to shortest 
available length 

Map on create with read and write access 
Initialize the WDB 

DATA WDB /"3400*0y "200y0*0>0> "203*0/ 



Example 8-3 Attaching to an Existing Region 
and Reading Data From It (Sheet 1 of 2) 
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C 

C Attach region 

CALL ATRG (RDBs» IDS ) 
C Check for error on attach 

IF <IDS .LT* 0) GOTO 100 
C Move region id to WDB 

WDB(4)=RDB(1) 
C Create and map window 

CALL CRAW (WDB? IDS ) 
Check for error 

IF (IDS »LT ♦ 0) GOTO 200 
C Get byte count and convert to word count 

NW0RD*=(IDATA(l) + l)/2 
C Print contents of region 

hl.0 WRITE (5»11) (IDATA(I) *I=2rNW0RD) 

Lll FORMAT (' ' >32A2) 

C Detach from region and delete it 

CALL DTRG (RUB* IDS) 
C Check for error 

IF (IDS .LT. 0) GOTO 300 
C And Jump to exit 



GOTO 500 

C 

C Error messages 

100 WRITE (5? 101) IDS 

.1.01 FORMAT (' ERROR ATTACHING TO REGION* DSW «-'»I4> 

GOTO 500 

200 WRITE (5x201) IDS 

201 FORMAT ( ' ERROR IN CREATING WINDOW? DSW ~',I4) 
GOTO 500 

300 WRITE (5»301) IDS 

301 FORMAT (' ERROR DETACHING FROM REGION? DSW 
C 

500 CALL EXIT 

END 



Example 8-3 Attaching to an Existing Region 
and Reading Data From It (Sheet 2 of 2) 
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SEND- AND RECEIVE-BY-REFERENCE 

If you create a private (unnamed) region, you have complete 
control over whether other tasks can have access to it. You 
specifically attach other tasks to the region by sending a packet 
containing a reference to the region. When you do that, you can 
also specify what access they have to the region. At the time, 
you must be attached with at least that much access yourself. 
Named regions, on the other hand, can be attached by any task that 
knows the name and has the appropriate access privileges to pass 
the protection check. 

Use the Send-by-Ref erence directive (SREF) to send a region by 
reference, with the following input parameters: 

Receiver task name 
WDB - Region ID 

offset into region - sent unchecked to receiver 
length to map - sent unchecked to receiver 
window status word - determines how receiving 

task is attached 
address of buffer - 8(10) word buffer which is 

sent to the receiver 
Event flag - if specified, set when the reference 
is received, not when it is queued up 
(in the receive-by-ref erence queue) 

The receiver task is attached to the region when the reference is 
queued. This avoids the problem of the region being deleted if 
the sender exits before the receiver receives the region. 
Remember that private regions are always marked for delete on the 
last detach. 

If you are using an event flag for synchronization, note that the 
flag should be used to notify the sender when the receiver 
receives the region by reference. It is not the same as the Send 
and Receive Data directives, where the flag is set when the 
reference is queued. That flag should be used to notify the 
receiver. 
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The receiver follows a somewhat modified procedure to access the 
region, as follows: 

1. Create window 

2. After reference is queued, Receive-by-Ref erence (fills in 
region ID in WDB) 

3. Map to region 

4. Use region 

5. Detach from region 

Use the Receive-by-Ref erence directive (RREF) to receive a 
reference to a region, with the following WDB input parameters: 

Window Status Word - WS.MAP (200(8)) for receive and map 

WS.RCX (100(8)) for receive data or exit 

Buffer Address - 10(10) word buffer for sender task 

name (in Radix-50 format) and data 

The following WDB output parameters are returned, all as set by 
the sender : 

Region ID 

Offset into region 

Length to map 

Window status word - describes how attached 

If the WS.MAP bit is set, the Executive maps the window to the 
region, using the offset, length, and window status word access as 
sent. If a separate Map directive is used, the receiver can first 
check and/or modify those parameters before mapping to the region. 
WS.RCX set tells the Executive that the task is to EXIT if there 
are no packets in the Receive-by-Ref erence queue. 



290 



DYNAMIC REGIONS 



Examples 8-4 and 8-5 show how to create a pair of tasks, a sender 
task and a receiver task. The sender, Example 8-4, creates a 
private region, initializes it, and sends a reference to it to the 
receiver. The receiver, Example 8-5, in turn receives the 
reference, displays the data, and then exits. One run session is 
included for both examples. The following notes are keyed to 
Example 8-4. 

Q The RDB for the region. The name is defaulted to create a 
private region. 

Q The WDB for the virtual address window. The length 
actually mapped will be returned after mapping. Read 
access is automatic for map, so WS.WRT gets read/write 
access. 

Q Create and attach to region, create virtual address window 
and map it to the region. 

O Fill the region with ASCII M's. 

Send-by-Ref erence to RCVREF (Example 8-4) . Event flag 1 
will be set when RCVREF actually does a 
Re ceive-by-Ref erence . 

O Display message saying region created and sent. Then wait 
for event flag 1 to be set. 

Display message saying RCVREF received region. 

Exit. The Executive will detach us from the region. Note 
that even if SNDREF exits before REVREF received, the 
region will not be deleted because RCVREF is attached when 
the reference is queued. The region is deleted only after 
both SNDREF and RCVREF detach. 
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PROGRAM SNDREF 

C 

C File SNDREF ♦ FTN 
C 

C This program creates a 64™ word unnamed region and 
C fills it with ASCII characters* It then sends it 
C reference to task RCVREFy and waits for RCVREF to 
C receive the region ♦< This is signalled bw event flag 
#1 ♦ ) SNDREF then prints a message and exits* Since 
the area is unnamed y it is automatically deleted when 
C the last attached task exits* 
C 

C T a s k - b u i I d i n s t r u c t i o n s ♦ 



C 

C >L INK/MAP/CODE ♦ FPP/OPTIONS SNDREF y LB *♦ C .1 y 1 .1F0R0TS- 

C ->/I...IBRARY 

C Option? UNDWS==1 

C Option? VSECT^DATAJ 1 60000 t 200 

C Option? <RET> 





C Install and run instructions* RCUREF must be installed* 
C Run SNDREF first y then run RCVREF* 



C 

C RDB ~ Region definition block with the following 

C properties* 

C Size 2 32-word blocks 

C Name none 

C Partition GEN 

C Protection WG ♦ none y S Y ♦ RUED y OU ♦ RUED y 

C GRJnone 
C Attach on creation 

C Read and write access desired on attach 

C 

C WDB : - : Uindow definition block with the following 

C properties* 

APR 7 

C Size 2 32--word blocks 

C Offset in region 32--word blocks 

C Length of region 2 32-word blocks 

C Map on create with write access 

C 

INTEGER RDB ( 8 ) y WDB < 8 > y RCV ( 2 ) 



C This common block will align with the address window 

COMMON /DATA/ I DATA (64) 
C Initialize the RDB 

DATA RDB/O y " 2 y y y 3RGEN y 3R y " 43 y " 170017/ 

C Initialize the UDB 

DATA UDB/"3400y0y "2y0y0y "2y "202y0/ 

C Name of receiver task 

DATA RCV/3RRCV y 3RREF/ 



Example 8-4 Send-by-Ref erence (Sheet 1 of 2) 
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C Code r 



Create region 
! Check for error 
Move region id to 
Create window 
! Check for error 



WDB 



C Fill 

10 ® 

C Send- 
C when 

e 



task? set event fla£ 1 



Error 

100 

110 

200 
210 



400 
410 

500 
510 

600 



CALL CRRG(RDBy IDS) ! 

IT (IDS ♦ LT ♦ 0) GOTO 100 

WDB(4)~RDB(1> ! 

CALL CRAW ( WDB y IDS) ! 

IF (IDS .LT. 0) GOTO 200 
region with data 
[DO 10 1 = 1 f 64 
[iDATA ( I ) ~ : ' MM ' 
by™ reference to receiver 
received 

CALL SREF ( RCV y 1 y WDB y y IDS ) 

IF (IDS .LT* 0) GOTO 400 ! Check for error 
TYPE *y' SNDREF HAS CREATED THE REGION AND HAS 
1 SENT IT TO RCVREF ♦ ' ! Display message 
CALL WAITFRd y IDS) ! Now wait for reception 

'IF (IDS ♦LT. 0) GOTO 500 ! Check for error 
[TYPE *y' RCv-REF HAS RECEIVED IT. SNDREF IS NOW 
[lEXITING.' ! Write message 

GOTO 600 ! And So exit 

hand I ins code 
WRITE (5y 110) IDS 

FORMAT (' ERROR CREATING REGION? DSW = 'yI4) 
GOTO 600 

WRITE (5*210) IDS 

FORMAT (' ERROR CREATING WINDOW y DSW = 'yI4) 
GOTO 600 

WRITE ( 5 y 410 ) IDS 

FORMAT (' ERROR IN SEND~BY~REFERENCE y DSW ~ 'yI4) 
GOTO 600 

WRITE ( 5 y 510 ) IDS 

FORMAT (' ERROR ON WAIT y DSW « ' y.I4) 



O CALL EXIT 
END 



Example 8-4 Send-by-Ref erence (Sheet 2 of 2) 
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The following notes are keyed to Example 8-5. 

Q WDB for virtual address window. The size is 200(8) 
32-word blocks, a full 4K words. The offset into the 
region, the length to map, and the access will be filled 
in on receive. Since the length to map sent by SNDREF is 
two blocks, 2 will be used in mapping. Note that the 
window can be more than two blocks long. WS.MAP must be 
left clear until after the window is created. Otherwise, 
the Executive will try to map the window to the region, 
causing an error. See the discussion which follows. 

Q Create the virtual address window. 

WS.MAP (200(8)) must be set in the Window Status Word 
(word 7) of the Window Definition Block, so that the task 
will map as part of the Receive-by-Ref erence . 

Q Receive-by-ref erence and map. 

Q Get length actually mapped (two blocks, same as length of 
region) and convert from blocks to bytes. Just display 
that many characters. 

O Display all characters with one WRITE. 

O Exit. The Executive will detach the task from the region. 
When both tasks have detached, the region will be deleted. 

The receiver may map after the receive-by-ref erence or as part of 
the receive-by-ref erence . If the receive-by-ref erence and the map 
are combined in one directive, issue the Receive by Reference 
directive with the WS.MAP bit set. In that case, the WS.MAP bit 
must be clear when the window is created since you can't map until 
you receive. This is necessary because even though the receiver 
is attached to the region when the reference is queued up, the 
region ID isn't filled in the WDB until the receiver executes the 
Receive-by-Ref erence directive. So if you receive and map in one 
call, issue the Create Address Window directive with the WS.MAP 
bit clear, and then set it before issuing the Receive-by-Ref erence 
directive. If you use a separate Map directive, the WS.MAP bit 
can be left clear. 
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PROGRAM RCVREF 

C 

C File RCVREF ♦ FIN 
C 

C Program to recei ve~by--ref erence 3 region from SNDREF? 
C map to the region* re3d ASCII data from the region? 
C detach from the region? and exit* The region will he 
C deleted on last detach* 
C 

C Task-build instructions* Include these options 
C WNDWS^l 

C v"SECT=DATA* 160000* 20000 

C 

C Install and run instructions* RCVREF must be installed* 



C Run SNDREF first? then run RCVREF* 
C 

C WDB ™ Window definition block with* 
C APR 7 

C Size 200(8) 32~wo rd blocks 

C Allow for full APR use 

C These are filled in on receive? as set by sender* 

C Offset in region 32~word blocks 

C Length of region 32-word blocks 

C reset after mapping 

C Access 



C NOTE* Must map after receiving (or as part of receive) 
INTEGER WDB(8) 
DATA WDB/"3400?0? "200?0?0?0?0?0/ 
C This common block will align with the address window 

COMMON /DATA/IDATA( "10000) 
C Create address window- — do not map at this time 

CALL CRAW (WDB? IDS) 
C Check for error on create 

IF (IDS ♦ LT ♦ 0) GOTO 200 
C Now set WDB status for mapping—will be done by recei ve-by-ref erence 

WDB(7)=WDB(7)+"200 
C Recei ve-by- reference and map 

CALL RREF ( WDB? ? IDS) 
C Check for error 

IF (IDS *LT* 0) GOTO 100 



Example 8-5 Receive-by-Ref erence (Sheet 1 of 2) 
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C Calculate number of words of data - length in blocks 
C returned at WDB(6) 

O NCHAR * 32*WDB<6) 

©rWRITE(5>10> < I DATA < I ) » I«l » NCHAR) 
[FORMAT (' '*32A2) 
C Go e;-;it 

GOTO 300 
C Error messages 

.1.00 WR.TTE<5vll0)IDS 

:U0 FORMAT <' ERROR ON RECEIVE-BY-REFERENCE> DSW *'>I4> 

GOTO 300 
200 WRITE < 5 9 210) IDS 

2.10 FORMAT (' ERROR CREATING WINDOW* DSW «'»I4> 

300 Q CALL EXIT 
END 



Run Session 

>INS RCVREF 
>RUN SNDREF 

SNDREF HAS CREATED THE REGION AND HAS SENT IT TO RCVREF ♦ 
RUN RCVREF 

RCVREF HAS RECEIVED IT* SNDREF IS NOW EXITING ♦ 
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM 
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM 



Example 8-5 Recei ve-by-Ref erence (Sheet 2 of 2) 
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THE MAPPED ARRAY AREA 

A large core resident data area may be set up by using the FORTRAN 
VIRTUAL statement. The VIRTUAL statement provides the Task 
Builder with the information required to create a mapped array 
area. The VIRTUAL statement is very similar to the DIMENSION 
statement except that all space reserved for a VIRTUAL array is in 
a separate area within the task region. 

Figure 8-3 shows a task using a mapped array area. The Task 
Builder sets things up so that when the task is initially loaded, 
the task region is larger than normal, with the mapped array area 
set aside in memory immediately below the task header. The task 
is automatically attached to the region since it is part of the 
task region. 

The area may be any size as long as the task image and the mapped 
array area fit into the partition. This means that it may be 
larger than 32K words. However, due to the subscript limitation 
of 32767 in FORTRAN, a single array cannot have more than 32767 
elements. Typically, the virtual address window maps only a 
portion of the region at a time using a single APR. Once you have 
referenced an element in a virtual array, the APR is set up to map 
to the nearest 4K boundary in the array. Hence, assuming an 
integer array I ARRAY , if your first reference is to IARRAY(l), 
then any element in the virtual array between IARRAY(l) and 
IARRAY(4096) can be maped with the current setting of the APR. 

However, if a reference is made to an element with a subscript 
higher than 4096, the APR used for the 4K window must be remapped. 
Hence, consecutive references to I ARRAY ( 1 ) , IARRAY ( 5000 ) , 
I ARRAY ( 2) , IARRAY (5001) , etc., will cause a remapping on each 
reference, thereby inducing some additional overhead. Note that 
all mapping is transparent to the user; however, knowledge of how 
mapping is performed, and when, can aid you in designing your 
programs to reduce the overhead required by remapping. 

Since the area isn't set aside until the task is loaded into 
memory, any initialization of the area must be performed at run 
time . 
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160000 APR 7 
APR 6 
APR 5 
APR 4 
APR 3 
APR 2 
APR 1 
APR 



VIRTUAL 
MEMORY 



WINDOW 

(4K WORDS) 



TASK 
IMAGE 

(28K WORDS) 



HEADER & STACK 



Q INITIAL LOAD AND MAP 

(i) TOTAL SPACE INITIALLY 
ALLOCATED. 4K WORD 
AREAS MAPPED AS 
NEEDED. 




PHYSICAL 
MEMORY 



TASK 
IMAGE 



HEADER & STACK 



MAPPED 

ARRAY 

AREA 

(32K WORDS) 



Figure 8-3 The Mapped Array Area 
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Example 8-6 shows how to create and use a mapped array area. The 
following notes are keyed to the example: 

O Create the virtual array I DATA with 32000 elements. 

Q Data to be placed into various parts of the virtual array. 

Put 'Al' into I DATA ( 1 ) and 'G7' into I DATA ( 2) . After the 
first reference, the mapping is set up to allow reference 
to any element up to IDATA(4096) without remapping. 

O Put data into elements IDATA(4097) and IDATA(4098). Note 
that the window had to be remapped to access the second 4K 
of the mapped array. This is transparent to the user. 

O Put data into the third 4K block. Remapping needed. 

Q Put data into the fourth 4K block. Remapping needed. 

Q Retrieve data from each of the four 4K blocks. Remapping 
required for each reference. The mapping order for 
displaying the data is different just to show that the 
order need not match the original order for placing the 
data into the region. 
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PROGRAM VIRTAR 



C File VIRTAR.FTN 
C 



VIRTAR makes use of the mapped array area by us ins! a 
FORT AN virtual array* It places data in 4 different 
4K word blocks of the area and then displays the 
data at the terminal* 



C 
C 
C 
C 
C 

INTEGER DATA y DATE v DATC y DATD y DATG 
C Set up the virtual array in the mapped arra\d area 

VIRTUAL I DAT A < 32000) 
C Define data values to be placed in the array 

0["DATA DATA y DATE y DATC / ' Al ' r ' E2 ' y ' C3 ' / 
[DATA DATD y DATG /'D4'y'G7'/ 
C Place data in 1st 4KW block/ I DATA < 1 ) - IDATA (4096) 
A pCDATA < 1 > ™DATA 
V |_1DATA(2)"-=DATG 
C - Place data in 2nd 4KW block/ IDATA (4097) - IDATA (8192) 

OflDATA<4097)^DATE 
[IDATA < 4098 ) ~ : DATG 
C Place data in 3rd 4KW block/ IDATA (8193) - IDATA < 12288 ) 
A riDATA(8193)*DATC 

L n ' ATA<8194)::::r,ATG 
C Place data in 4th 4KW block/ IDATA (12289) -IDATA ( 16384 ) 

©[IDATA (1 2289) *DATD 
[i DATA (12290 >«DATG 
C Write data from 1st 4KW block 

WRITE (SylOO) IDATA ( 1 ) y IDATA (2) 
C Write data from 2nd 4KW block 

WRITE (SylOO) IDATA(4097) yIDATA(4098) 
C Write data from 4th 4KW block 

WRITE (SylOO) I DATA ( 12289 ) ? IDATA (12290) 
C Write data from 3rd 4KW block 

WRITE (5yl00) IDATA(8193) y IDATA ( 8194 ) 
.1.00 FORMAT (' 'yA2yA2> 

CALL EXIT 
END 



Run Session 

>RUN VIRTAR 

A1G7 

B2G7 

D4G7 

C3G7 



Example 8-6 Use of the Mapped Array Area 
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Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all lab problems. Check your answers against the 

solutions provided, either in that book or in on-line files. 

If you think that you have mastered the material, ask your course 

administrator to record your progress in your Personal Progress 

Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, return 

to this module for further study. 
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INTRODUCTION 

The RSX-11M file system is composed of three parts. 

• File structures - the organization and data structures 
maintained on the mass storage volumes themselves 

• Ancillary Control Processors (ACPs) - tasks which maintain 
the file structures and provide access to them 

• File access routines - provide user-written tasks with an 
interface to ACPs, which provide and maintain organization 
within files. 

This module reviews some basic information about file storage, and 
provides general information about the RSX-11M primary file 
structure called FILES-11, and its ACP. This module also presents 
an overview and comparison of the two supplied file access 
subsystems, File Control Services (FCS) and Record Management 
Services (RMS) . The following module provides details on 
programming using FCS, which is the more widely used subsystem. 



OBJECTIVES 

1. To describe the steps involved in file I/O 

2. To describe the FILES-11 structure and how the F11ACP 
maintains that structure during file I/O 

3. To identify the advantages of using either FCS or RMS for 
file access. 



RESOURCES 

1. IAS/RSX-11 I/O Operations Reference Manual , Chapters 1 and 
5 

2. RMS-11 User's Guide 
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OVERVIEW 

Quite often in an application you need to store data on a 
peripheral device (disk, magtape, etc.) for later retrieval. To 
write such an application, you must know something about the 
different devices which are on your system. In addition, you must 
understand the file structure and its support systems. Once you 
know that, you can learn the procedure for actually performing I/O 
operations. 



TYPES OF DEVICES 



Record-Oriented Devices 

Record-oriented devices have the following characteristics. 

• Data is handled a record at a time. 

• There is no file structure. 

Terminals, line printers, and card readers are all record-oriented 
devices. They are not designed for storage and fast retrieval of 
data, but are designed instead to support interactive sessions or 
provide hard copies of reports and other data. 

File-Structured Devices 

File-structured devices have the following general 
characteristics. The data they contain: 

• Can be handled in files 

• Can be stored and retrieved quickly 

• Is typically stored on a storage medium which can be moved 
from one device to another. 

Hard disks, floppy disks, and magtape are examples of 
file-structured devices. The following definitions should prove 
helpful in our discussion. 

a file - a collection of related data; therefore, a 
logical unit of mass storage. 
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volume - a physical unit of mass storage consisting of a 
recording medium and its packaging. Examples are a disk 
pack, a reel of tape, a diskette, and a DECtape II 
cartridge. 

Types of File-Structured Devices - There are two types of 
file-structures devices, sequential and random-access. The type 
is determined by the kind of access to data on it. 

Sequential devices have the following characteristics. 

• Data is retrieved in the same order as written 

• New data is always appended at the logical end of the 
tape, after the last data written 

• data cannot be written in the middle of the volume without 
losing the data past that point. 

Magtape and cassettes are examples of sequential devices. In 
essence, data is stored in order as written. To access any data, 
all data before it on the tape must be read first. 

Under RSX-11M, the magtape ancillary control processor (MTAACP) 
supports the ANSI file structure. 

The MTAACP supports the following file setups:' 

• A single file on a single volume 

• A single file on multiple volumes 

• Multiple files on a single volume 

• Multiple files on multiple volumes 

Random-access devices, also called block-structured devices or 
block-replaceable devices, have the following characteristics. 
They can: 

• Store and retrieve data in units called blocks 

• Write or read blocks in any order 

• Rewrite blocks without interfering with other blocks. 

Hard disks (RL01/02, RP06, RM02/03) , diskettes (RX11, RX211) and 
DECtape II are examples of random-access devices. 
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The FILES-11 file structure, the standard RSX file , structure, is 
supported by the FILES-11 ancillary control processor (F11ACP) . 
F11ACP supports multiple files on a volume, but a file may not 
extend across volumes. The COPY command (PIP in MCR) maintains 
the FILES-11 structure during transfers of files within a given 
device and between FILES-11 devices on a system. 

The ANSI file structure is useful for transfers of files between 
different (possibly non-DIGITAL) systems. FILES-11 is useful 
between DIGITAL systems under RSX-11M, RSX-11M-PLUS , IAS and VMS 
if the two systems have a device in common (e.g., both systems 
have RL02s) . The FLX utility is provided to facilitate transfers 
between RSX and other DIGITAL systems which don't support 
FILES-11, or between systems which support FILES-11 (even between 
two RSX-11M systems) which do not have a common FILES-11 device. 
In that case, the FLX transfer is typically made on magtape, using 
DOS or RT-11 format. 
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COMMON CONCEPTS OF FILE I/O 
Common Operations 

File I/O is often used to perform the following operations. 

• Creating a file 

• Deleting a file 

• Modifying existing data within a file 

• Appending new data to a file (or extending the file). 

Steps of File I/O 

Use the following three basic steps to do file I/O. 

1. Open the file. 

Specify a LUN and the file. The ACP connects a task 
LUN to the file. Specify the access rights desired. 
The ACP checks against the file protection code. If 
you are creating a new file, specify the file 
characteristics (e.g., format and initial length). 

2. Perform the I/O operations. 

Use macros to invoke subroutines to store data in the 
file and/or retrieve data from the file. 

3. Close the file. 

Notify the system that the file operations are 
completed, so that appropriate cleanup work can be 
performed . 
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FILES- 11 

In order to use FILES-11, you need to understand its structure and 
how to interact with it. 



FILES-11 Structure 

A block is the smallest unit of storage which is read from, or 
written to, a FILES-11 device. Typically, the blocks are 256(10) 
words or 512(10) bytes long. Some devices divide or format their 
volumes into pieces which are 256(10) words long, and others do 
not. Therefore, the FILES-11 structure does some converting or 
mapping so that you work with logical blocks which are all 
standard size. When the volume is formatted, logical block 
numbers are assigned to each 256(10) word area on the disk, 
starting with logical block 0. Generally, the position of data on 
a FILES-11 volume can be described in three alternate ways, by: 

• Physical location 

• Logical block number 

• Virtual block number 

Table 9-1 compares the three ways. Figure 9-1 shows an example of 
the mapping among the different methods. Typically, you will 
reference data only within files. The files are referenced by 
virtual block numbers within the file, starting with 1. Logical 
block numbers are assigned to the entire disk, starting from 0. 

The system converts virtual block number references to logical 
block number references. For example, if you request a read of 
virtual block 5, the system looks at the mapping and finds that 
this corresponds to logical block 1622(8). This logical block, in 
turn, is mapped to one or more specific sectors on the disk, which 
are read from the disk. 
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Table 9-1 Comparison of 


Physical , Logical and Virtual Blocks 


Designation 


Size 




How Designated 


Physical 


Depends 

ImIC V i^C 


on 


On multi-platter disks, 

ucaiy ua lcu '-'Y uyx inuci , ulci^i\ 

and sector 


Logical 


256 (10) 
words 




Numbered in increments relative 
to the beginning of the volume, 
starting with 


Vi rtual 


256(10) 
words 




Numbered in increments relative 
to the beginning of a file, 
starting with 1 



Typically, data is accessed as records, units which are not 
exactly one block or 512(10) bytes long. A record is a unit of 
user specified size, corresponding, for example, to a single bank 
account or a single line of text at a terminal. 

Figure 9-2 shows how the operating system handles a request to 
read a record using FCS. The first row shows a FORTRAN READ. The 
FORTRAN READ instruction is converted by the compiler to a GET$ 
call to the File Control Services (FCS) to l^ead that record. In 
MACRO, you will issue the GET$ call yourself. FCS checks to find 
out which virtual block within the file contains that record and 
issues the QIO directive for you. The Executive converts the 
virtual block number to its corresponding logical block number and 
issues a read logical block QIO. The driver then converts the 
logical block number to the appropriate physical locations, and 
reads a block of data into memory. The record itself will then be 
located within the block of data. 

The second row shows a BASIC-PLUS-2 READ under the Record 
Management Services (RMS) . The BASIC-PLUS-2 compiler converts the 
READ to a RMS $GET call. RMS converts this to a QIO, to read the 
corresponding virtual block. From that point on, the steps are 
just like those in the FORTRAN example. 
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file SAMPLE.TXT; 1 



VIRTUAL 
BLOCK #'S 
(IN THE 
FILE) 



1 


2 


3 


4 


5 


6 


7 


10 



\ 



\ 



\ 



\ 



\ 



\ 



LOGICAL | 

BLOCK ... 102 
#'S (ON I 
THE VOLUME) \ 



103 



104 



457 



460 



PHYSICAL 
LOCATIONS 
(ON THE 
VOLUME) 



\ 



\ 



\ 



\ 



\ 



\ 



\ 



^ \ 1 



\ 



1104 



1621 



1622 



/ 



I / 



/ 



/ 



/ 



/ 



* \ i // 



NOTE: BLOCK NUMBERS ARE IN OCTAL 



Figure 9-1 Example of Virtual Block to Logical Block, 
to Physical Location Mapping 
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FORTRAN 



MACRO-11 

ENTERS HERE 



• 
• 
• 

READ (5,10) 


COMPILER ' 


• 
• 

GET$ 
• 


FCS^ 


• 
• 
• 

QIO IO.RVB. 

• 


EXEC 
F'11'ACP 


• 
• 
• 

QIO IO.RLB 
• 


DRIVER m 




1DATA 
• 












• 
• 




• 
• 




• 
• 




• 
• 


TRANSFER 



FORTRAN RECORD 



BASIC-PLUS-2 



FCS RECORD 



VIRTUAL 
BLOCK # 



LOGICAL 
BLOCK # 



FROM PHYSICAL 
LOCATIONS ON 
DISK 



RMS 







• 


• 




• 


• 




• 


READ DATA 


COMPILER 


$GET 




• 




• 


• 




• 


• 




• 



BASIC-PLUS-2 
RECORD 



RMS RECORD 



Figure 9-2 How the Operating System Converts Between 
Virtual, Logical, and Physical Blocks 



Figure 9-3 shows the FILES-11 structures which are used to support 
virtual-to-logical block mapping. Every FILES-11 volume has a 
number of system files on it, one of which is the Index File 
(INDEXF.SYS) . The Index File contains certain blocks which are 
for system use, plus a file header block for each file on the 
volume . 

Each file header block contains file retrieval pointers which are 
used in mapping virtual blocks to logical blocks. Each file 
retrieval pointer locates a range of contiguous logical blocks. 
The first byte tells how many contiguous blocks are in the group, 
and the next three bytes specify the logical block number of the 
first block in the group. Therefore, in the figure, there are 
five contiguous blocks, starting with logical block 336851(10). 
Virtual block 1 = logical block 336851(10), vb 2 = lb 336852(10), 
vb 3 = lb 336853(10), vb4 = lb 336854(10), and vb 5 = lb 
336855(10). The next group of blocks, starting with virtual block 
6 has 51(10) blocks and begins at logical block 336900(10) up 
through logical block 336950(10). The last 17(10) virtual blocks 
(virtual blocks 57(10) to 73(10)) begin at logical block 
337006(10) up through logical block 337022(10). These file 
retrieval pointers are updated each time a change in block 
allocation occurs as a result of a file I/O operation. 
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VOLUME 



INDEX FILE 




VBN 











FILE 
HDR 


FILE 
HDR 


FILE 
HDR 


FILE 
HDR 


• • • 


FILE 
HDR 


1 


2 


3 


4 


5 


6/ 


7 


\ 10 




N 



/ 



/ 



/ 



/ 



\ 



\ 



\ 



\ 



FILE HEADER 
FILE 3 

-A 



RETRIEVAL POINTERS 



/ 



/ 



L 



\ 



SIZE 




1ST 


LBN 


v 

-* 





SIZE 
5. 
51. 
17. 



1ST LBN 
H:005 L:021723 = 336851. 
H:005 L: 022004 = 336900. 
H:005 L -022156 = 337006. 



Figure 9-3 FILES-11 Structures Used to Support 
Vi rtual-to-Logical Block Mapping 
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Directories 

The operating system identifies files by file IDs, which are used 
to calculate the location of the file header within the index 
file. When you need to locate a file, it is difficult to remember 
where it is on the disk, or even what its file ID is. Instead, 
you use a file specification, a more English-like way of 
identifying a file. An example of a file specification is: 
DR1: [5,6] SAMPLE. TXT;1. Tasks you write also usually identify 
files with a file specification. Directories are structures set 
up on a FILES-11 volume that are used to group files together, and 
to convert file specifications to file IDs. 

A directory is a list of files belonging to a single user, or 
grouped together for other organizational purposes. An example of 
files grouped together for organization is the libraries in User 
File Directory (UFD) [1,1] on the system device. On a FILES-11 
volume, a directory is a special file containing a list of the 
files belonging to that user or group. For each file, the list 
has: 

• The file specification: name, type, and version number 

• The file ID 

The file ID consists of a file number and a sequence number. The 
file number identifies the offset within the index file to the 
virtual block containing the file's file hea'der. The sequence 
number is used to distinguish this file from previously deleted 
files which used the same file header. There are two levels of 
directories on a volume, as follows. 

• One Master File Directory (MFD) which is directory [0,0] 

• One or more User File Directories (UFDs) 

Figure 9-4 shows the relationship between the two levels and the 
files. The MFD contains a list of the system file, plus one entry 
for each UFD on the volume. Each UFD file has a name of the form 
gggmmm.DIR, where [ggg,mmm] is the user identification code (UIC) 
of the owner. Each UFD contains a list of the files in that 
directory. 
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MFD 
[0,0] 





HIYA.MAC;1 



FLY.TXT;1 



IZZY.TXT;1 



OZY.TXT/1 



LOGIN.CMD;1 



TK-3965 



Figure 9-4 Directory and File Organization on a Volume 



Figure 9-5 shows the steps used in locating and accessing the 
blocks of the file DR2 : [5,6] SAMPLE • TXT ; 1 • The device name, DR1 : 
tells which device or volume to look on. The operating system 
reads the MFD file header to find the retrieval pointers for the 
MFD file itself. It converts the virtual blocks to logical blocks 
and reads the blocks of the MFD file. It searches through the 
directory list for the UFD [5,6], namely the file 005006. DIR. 

When it finds that name in the list, it uses the file ID to locate 
the UFD file header. It reads the retrieval pointers there, 
converts the virtual blocks to logical blocks, and reads the 
blocks of directory [5,6]. It looks for an entry SAMPLE . TXT; 1 . 
When it finds that entry, it uses the file ID to locate the 
SAMPLE. TXTs file header. It then reads the retrieval pointers in 
the file header, converts the virtual blocks to logical blocks, 
and reads the blocks of the file itself. 

If this sounds like a lot of work, it is. Later, you will learn 
about a way to go directly to the file header using the file ID if 
a file is opened a second time during a task's execution. 
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DR1:[5,6]SAMPLE.TXT;1 



MFD 
HEADER 



RETRIEVAL 
POINTERS 



• 






• 






• 






005005.DIR 


FILE 


ID 


005006. DIR 


FILE 


ID 


• 













MFD 



UFD 

HEADER 



RETRIEVAL 
POINTERS 



SAMPLE.TXT;! FILE ID 



UFD [5,6] 



FILE 
HEADER 



RETRIEVAL 
POINTERS 



THIS IS A SAMPLE FILE 



FILE 

SAMPLE.TXT;1 



Figure 9-5 Locating a File on a FILES-11 Volume 
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Five Basic System Files 

There are five basic system files found on all FILES-11 volumes. 
They are all created when the volume is initialized and are all 
entered in the MFD. Two of these, the Index File and the Master 
File Directory, have been mentioned previously. The five files 
and their purposes are as follows. 

• The Index File: INDEXF.SYS. 

Boot block - used when a system volume is bootstrapped 

Home block - contains volume identification and other 
information 

Index file bitmap - a record of which header blocks 
are in use; used by F11ACP when allocating header 
blocks to files 

File header blocks for all files on the volume 

• The Storage Map: BITMAP. SYS. 

A record of which blocks on the volume are in use 
Used by F11ACP when allocating blocks to files 

• The Bad Block File: BADBLK . SYS . 

- A list of blocks on the volume known to be bad 

• The Master File Directory: 000000. DIR. 

Entries for the five system files 
An entry for each UFD file 

• The System Checkpoint File: CORIMG.SYS. 

- Space used for checkpointing if the system manager 
allocates space in it. 
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Functions of the ACP 

The F11ACP maintains the FILES-11 structure on a volume during its 
use. 

The most elementary functions performed by the ACP are as follows. 

• Maintaining the File Header Blocks. This includes: 

- Allocating and initializing a file header when a file 
is created 

Recovering a file header for reuse when a file is 
deleted 

Maintaining file attributes such as protection code, 
length, etc. 

Maintaining the file retrieval pointers 

• Maintaining directories. This includes: 

Creating directory entries when a file or UFD is 
created, or when a file synonym is created (e.g., by 
the PIP /EN switch) 

Removing entries from directories when a file is 
deleted or a file synonym is removed (e.g., by the PIP 
/RM switch) 

• Maintaining block allocation. This includes: 

Allocating blocks to files when a file is created or 
extended 

Recovering blocks for reuse when a file is deleted or 
truncated 

• Controlling and facilitating task access to files. This 
includes : 

Checking protection codes to determine access rights 

Connecting a task's LUN to a file to allow virtual 
block I/O 

Controlling shared access to files. 
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Table 9-2 shows the F11ACP functions performed when you request 
some typical file I/O operations. 



Table 9-2 Examples of Use of F11ACP Functions 



Operation Requested 



Functions Performed by F11ACP 



Create a new, permanent file 
and write data to the file. 



1. Allocate a header for the file, 

2. Allocate blocks to the file, 
when it is opened and/or when 
data written requires that ex- 
tensions be added. 

3. Create a directory entry for 
the f ile . 

4. Assign a LUN to the file. 

5. When the file is closed, write 
the updated file attributes to 
the file header, deassign the 
LUN 



Read data from an existing 
f ile . 



1. Assign a LUN to the file. 



Delete a file. 



1. Remove the directory entry for 
the file. 



2. Deallocate the blocks of the 
file. 

3. Deallocate the header for the 
file. 



Append data to a file. 



1. Assign a LUN to the file. 



2. Allocate extra blocks to the 
file. 



Create a temporary (scratch) 
f ile . 



1. When file is opened, allocate 
a header, allocate blocks, and 
assign a LUN. (No directory 
entry is created.) 

2. When file is closed, de- 
allocate blocks, deallocate 
header, and deassign LUN. 
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Figure 9-6 shows the flow of control during the processing of an 
I/O request. This figure parallels Figure 9-2, which shows how 
the operating system converts virtual blocks to logical blocks to 
physical locations. 

The user task issues a read record request which is converted by 
an FCS routine in the user task to a QIO, to read a virtual block. 
The Executive converts the virtual block number to a logical block 
number, using file retrieval pointers in pool. These retrieval 
pointers are built by F11ACP from the retrieval pointers in the 
file header. The Executive issues a read logical block request to 
the driver. The driver converts the logical block number to the 
actual physical locations and copies the block into the user 
buffer. 

For additional information on the FILES-11 structure, see Chapter 
5 of the IAS/RSX-11 I/O Operations Reference Manual. 



USER TASK 
-READ RECORD 

FCS OR RMS 
►QIO IO.RVB 

BUFFER 



POOL 

RETRIEVAL POINTERS 



FILE HEADER 



EXEC 




DRIVER 




MS 



F11ACP 




FILE BODY 



Figure 9-6 Flow of Control During the Processing of an 

I/O Request 
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OVERVIEW AND COMPARISON OF FCS AND RMS 



Common Functions 



The File Control Services (FCS) and the Record Management Services 
(RMS) both offer easy methods for performing file I/O. The 
operator or programmer need not be concerned with all the 
nitty-gritty details, but can instead let FCS or RMS take care of 
them. Both perform the following functions: 



• Serve as an interface to the ACPs 



• Allow I/O to the virtual blocks of a file on a 
block-by-block basis (Block I/O) 

• Divide files into logical records and allow I/O to 
individual records within a file (Record I/O) 

• Allow the programmer to process records using one of the 
following buffers (Figure 9-7) 

A buffer reserved by the programmer with another 
buffer transparently used by FCS or RMS (move mode) 

Directly in the buffer used by FCS or RMS (locate 
mode) 

• Allow device independent I/O - the routines are written to 
work correctly with terminals, disks, etc. 



• Provide mechanisms for controlling shared access to files. 

Beyond that, FCS and RMS each offer a variety of file 
organizations, record types, and access modes. These are 
described in the following sections. 
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MOVE MODE 



TASK 

(IN MEMORY) 




LOCATE MODE 



DISK 




MOVE BLOCK 
TO INTERNAL 
BUFFER 

(IF NECESSARY) 



TASK 

(IN MEMORY) 




POINTER 
/ 

/ POINT 
/ POINTER 
/ TO RECORD 

/ 

/ 



/ 

/ 










|abc • • • 













INTERNAL 
BUFFER 



TK-7742 



Figure 9-7 Move Mode and Locate Mode 
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FCS FEATURES 



File Organizations 

Essentially, all FCS supported files are sequential, meaning that 
new records are added at the end of the file, and records are 
stored in the order they are written. Figure 9-8 shows a file 
with sequential organization. 



CELL NO. 1 2 3 4 5 n 




TK-7748 



Figure 9-8 Sequential Files 



Supported Record Types 

FCS supports two record types, fixed-length records and 
variable-length records. Variable-length records may be sequenced 
or nonsequenced . An example of each type of file is shown below 
with the following three records: 

12345 

123 1234 

AAAA BBBB CC D 

The examples are in DMP format; the six-digit number on the left 
is the byte count in octal of the first byte in that row. Then 
16(10) = 20(8) bytes follow in order in octal. Below each byte in 
octal is its equivalent in ASCII. An underscore (_) stands for an 
ASCII blank. Consult the examples as you read the description of 
each record type which follows. 
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Examples : 



Fixed-Length Records (record length 



000 


061 


062 


063 


064 


065 


040 


040 


040 




1 


2 


3 


4 


5 








020 


040 


XXX 


061 


062 


063 


040 


061 


062 






pad 


1 


2 


3 




1 


2 


040 


040 


040 


040 


XXX 


101 


101 


101 


101 










pad 


A 


A 


A 


A 


060 


040 


104 


040 


040 


040 


XXX 


XXX 


XXX 






D 








pad 







Variable-Length Records 

000 005 000 061 062 063 064 065 

1 2 3 4 5 

020 063 064 016 000 101 101 101 

3 4 AAA 

040 040 104 xxx xxx xxx xxx xxx 
D 



Sequenced Variable-Length Records 



= 17(10)) 



040 


040 


040 


040 


040 


040 


040 


040 


063 


064 


040 


040 


040 


0l0 


040 


040 


3 


4 














040 


102 


102 


102 


102 


040 


103 


103 




B 


B 


B 


B 




C 


C 


xxx 


xxx 


xxx 


xxx 


xxx 


XXX 


xxx 


xxx 



xxx 


010 


000 


061 


062 


063 


040 


061 


pad 






1 


2 


3 




1 


101 


040 


102 


102 


102 


102 


040 


103 


A 




B 


B 


B 


B 




C 


xxx 


XXX 


xxx 


xxx 


xxx 


xxx 


XXX 


xxx 



000 007 000 001 000 061 062 063 064 065 xxx 012 000 002 000 061 062 

1 2 3 4 5 pad 1 2 

020 063 040 061 062 063 064 020 000 003 000 101 101 101 101 040 102 

3_1234 A A A A _ B 

040 102 102 102 040 103 103 040 104 xxx xxx xxx xxx xxx xxx xxx xxx 

B B B C C D 
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Fixed-length records all contain the same number of bytes. 
Therefore, the location of the beginning of any record within the 
file can be computed from its record number. With all record 
types, each record begins on an even word boundary. This means 
that in files with fixed-length records, if each record contains 
an even number of bytes, the next record begins immediately after 
it. If, on the other hand, each record contains an odd number of 
bytes, one byte is unused after each record, and the next record 
begins at the next word boundary. This unused byte is called a 
pad byte. 

Variable-length records may each have different lengths. For all 
files with variable-length records, the first word of each record 
contains a byte count, telling how many bytes are in that record. 
For variable-length nonsequenced records, this count word is 
followed by the data itself. 

Following this, at the next word boundary, is the byte count for 
the next record and then its data. To locate a given record 
within the file, you must first read the byte count for the first 
record in the file. You can then use the byte count to locate the 
second record. You then continue reading byte counts and locating 
successive records until you reach the desired record. 

Variable-length sequenced records contain a byte count, a user 
specified sequence word, and then the data itself. The sequence 
word can contain the record number or any other user specified 
value. Variable-length sequenced records are not used much under 
FCS. They are supported to allow compatibility with RMS 
variable-wi th-f ixed-control records. 
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Table 9-3 compares the different FCS record types. 



Table 


9-3 Comparison of 


FCS Record Types 


Record 




Overhead 


Common 


Type 


Characteristics 


in File 


Appl ications 


Fixed-Length 


Record length 


None 


Files with 




set when file 




similar data 




created 




in each record 




Records all 




Bank account 




same length 




information , 




(shorter 




bad credit 




recoras paa— 




card lists, 




ded) 




etc • 


Var iabler-Length 


Records may be 


One word per 


Files with 


(nonsequenced) 


of different 


record (hold- 


varying con- 




lengths 


ing record 


tents among 






length) 


records 




First word of 




Files to be 




each record is 




printed 




a byte count 




Source and 








list files 


Var i able- length 


Variable length 


Two words per 


Infrequently 


(sequenced) 


records, with 


record (one 


used, except 




an additional 


for record 


for compati- 




word for a user 


length, for 


bility with 




specified se- 


sequence 


RMS. 




quence number 


field) 
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Record Access Modes 

FCS offers two record access modes, sequential access and random 
access. Table 9-4 compares the two access modes. The major 
difference is that with random access, the user can process 
records in any order (e.g., record 12, then record 4, then record 
29) . This is possible with fixed length records only, because FCS 
can calculate the position of each record within the file from the 
record number and the record size. 

With variable-length records, on the other hand, FCS can't locate 
record 12 unless it reads records 1 through 11 first, using the 
record length in the first word of each record to calculate the 
starting position of the next record. Therefore, you must use 
sequential access with variable length records. You may choose 
either of the two access modes for fixed length records, depending 
on how your application processes the records. 
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Table 9-4 Comparison of Sequential Access 

Random Access I/O 


I/O and 


Characteristics 


Sequential 


Random Access 


Devices supporting 
this type of access 


All devices 


Block-structured 
devices only 


Record types using 
this type of I/O 


All record types 


Fixed-length 
records only 


Sequence of records 
i n the file 


Determined by the 
order in which they 
are written to the 
file 


Usually determined 
by the order in 
which they are 
written to the file 


Order of processing 
records 


Usually the same 
order as in the 
file (one after 
another) 


In any order, as 
specified by the 
user (using the 
record number) 


Overhead if records 
are processed in 
same order as they 
are stored in the 
file 


Low 


Low, but not as 
low as sequential 


Overhead involved 
if records are 
processed in 
order different 
from how they are 
stored in the file 


Much higher than 
random access I/O 


Much lower than 
sequential I/O 



NOTE 

With sequential access, special system 
subroutines allow the user to save pointers 
to a record for much faster subsequent 
access. 



V 
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File Sharing 

A task which opens a file may choose one of the following options: 

• That no other accessor change any data in the file while 
it has access ("shared" read, "exclusive" write). 

If this task desires read access, other accessors may 
have simultaneous read access, but no other accessor 
may have simultaneous write access. 

If this task desires write access, no other accessor 
may have simultaneous read or write access. 

- Any access request causing a conflict is rejected. 

• That other accessors may change the data while it has 
access ("shared" read/write access) . 

If this task requests read or write access, other 
accessors may have simultaneous read or write access. 

Use extreme care - Any precautions against corrupted 
data are the responsibility of the accessors. 

• That no other accessor changes any block within the file 
which has already been accessed (block locking) . Shared 
access to the file is allowed, but: 

Each block which is written to is locked for exclusive 
write access. 

- Each block which is read is locked for shared read 
access. 

It is not recommended if accessing a large numbers of 
blocks, because each block lock uses four words of 
pool . 

- Any attempt to access a block which causes a conflict, 
returns an error. 
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RMS FEATURES 



File Organizations 

RMS supports three file organizations, sequential, relative and 
indexed. See Figure 9-9. Sequential files under RMS are the same 
as sequential files under FCS. A relative file is composed of a 
series of cells of uniform size. The cell size is greater than or 
equal to the largest record to be placed in the file. A single 
record may be written to a cell, or the cell can be empty. The 
cells may contain variable-length records. Variable-length 
records within relative files can be accessed randomly because 
each record is contained within a fixed-length cell. Also, when 
you read successive records in a relative file, empty records are 
automatically skipped. 

An indexed file is composed of records, plus one or more indexes 
which are used to access those records. Each index is used to 
retrieve records according to the contents of a particular field, 
or key, within the record. The data records themselves are 
ordered according to a primary key which you declare when you 
create the file. 

Figure 9-9 shows an indexed file with a single key, namely last 
name. In the example, the data records are in the bottom row, 
ordered alphabetically by last name. The index for this file 
contains two other levels, level 1 and level 2 (the root level). 

A search for a record begins at the root level. For example, to 
find the record with key value FRANCIS, search through the root 
level, checking for the first value which is greater than or equal 
to FRANCIS. The first such value is SMITH. Go to the next level 
and again search for the first value greater than or equal to 
FRANCIS; it is GROSS, the first value. Now go to the next level 
and search again; this time the value FRANCIS is found. Since 
this is level 0, we have found the record. 

As new records are added to the file, they are inserted in order 
at level of the primary index. The primary index structure is 
adjusted for the new entry at the same time. In addition, any 
alternate index structures for other keys are adjusted as well. 
There is always one primary key, and there may be as many as 
254(10) alternate keys. 
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END OF FILE 



RECORD 


RECORD 


RECORD 




RECORD 


1 


2 


3 




n 



SEQUENTIAL FILE ORGANIZATION 



CELL NO. 



RECORD 
1 



'//////////////, 
RECORD |EMPTYg RECORD 




RECORD 



RELATIVE FILE ORGANIZATION 



LEVEL 2 
(ROOT) 



DAVIS | SMITH | high key 



ANDREWS DAVIS 



GROSS MORRIS SMITH 



THOMAS high key 



ADAMS 
10246 



ANDREWS 


BAKER 


50406 


11022 



DAVIS 


EDSON 




FRANCIS 




GROSS 


HARRIS 


02139 


01142 




46423 




54966 


11462 



INDEXED FILE ORGANIZATION 



WELLS 
43168 



Figure 9-9 RMS File Organizations 



Level of the alternate keys contains pointers to the original 
location of the data record itself. If a data record is ever 
moved in order to maintain the index structure, a pointer is 
created and maintained in the record's original location, which 
points to the data record's new location. 

One specific advantage of an indexed file over a relative file is 
that an indexed file allows you to search for records using 
several different key fields, while only the cell number can be 
used with relative files. Even with a single key, indexed files 
offer keys consisting of any ASCII characters, in contrast to just 
a cell number for relative files. 

There is, of course, more space overhead required in the file for 
the index structures. In addition, more execution time is 
required to insert new records, because the index structures must 
be updated as well. We are keeping things rather simple in the 
discussion here. For additional information, see the 
RMS-11 User's Guide. 
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Record Formats 

RMS supports three record formats; fixed-length records, 
variable-length records, and variable-length records with fixed 
control. Fixed-length records and variable-length records are the 
same as fixed-length records and nonsequenced variable-length 
records respectively, under FCS. They are both supported under 
all three file organizations. 

Variable-length records with fixed-control (VFC) contain a 
fixed-length portion, for control, followed by a variable-length 
portion. The fixed control portion may be up to 255(10) bytes 
long. A sequenced variable-length record under FCS is the same as 
a VFC record with a 2-byte (one word) fixed control portion. 

An example of the use of VFC records is a bank account file, where 
some accounts have both savings and checking, and others have just 
one or the other. The fixed control portion could contain the 
account number plus an indication of the kinds of accounts 
contained in it. The variable portion contains the account 
information for those accounts. The length of this portion 
varies, depending on how many accounts the person has. VFC 
records are supported under sequential and relative file 
organizations only. 



Record Access Modes 

RMS supports three record access modes: sequential access, random 
access, and access by Record File Address (RFA) . Sequential 
access and random access are similar to the FCS access modes, 
except that they are applied differently for indexed files. 

For sequential access on an indexed file, the "next" record is the 
record with the next highest key value using the specified key, 
not the next record added to the file. For random access, a key 
value for a certain key is specified, and that record is located 
and accessed. To access a record by record file address, save 
pointers to the record (called its record file address or RFA) 
from one access, then use the pointers to subsequently access the 
record again. 

Table 9-5 describes the various access modes supported for each 
file organization and how they work. For additional information, 
see the RMS-11 User's Guide. 
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Table 9-5 Pile Organization, Record Formats, and Access Modes 



Sequential Relative Indexed 

Files Files Files 



Record 


Fixed 


Fixed 


Fixed 


Formats 


Variable 


Variable 


Variable 


Supported 


VFC 


VFC 




Access Modes 


Sequential 


Sequential 


Sequential 


Supported 


RFA* 


Random 


Random 






RFA* 


RFA* 


Sequential 


Writes and 


Writes to 


Accesses cells 


Access 


reads subse- 


subsequent 


in ascending 


Techniques 


quent records 


cells 


order accord- 






Reads from sub- 


ing to user 






sequent cells, 


specified key 






skipping empty 








ones 




Random 


Not allowed 


User specifies 


User specifies 


Access 




cell number of 


key and key 


Techniques 




record to be 


value to be 






accessed 


used in 








accessing 








records 


Record File 


Task can 


Same as sequen- 


Same as 


Address 


store RFA* of 


tial files 


sequential 


Techniques 


a record for 




files 




later return 







* Not available in FORTRAN. 
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File Sharing Features 

RMS offers more sophisticated file-sharing options than FCS. 
Sequential files can be shared for read access only. Relative and 
indexed files can be shared for read and write access. When 
opening a relative or indexed file, a task indicates one of the 
following options. 

• No other accessor can change data in the file while it has 
access ("shared" read, exclusive "write"). 

• Other accessors can change data, but subsets of the file 
are protected at a time, while in use. 

Relative and indexed files are divided into units called buckets 
(of user specified size, each 1 to 32(10) blocks long). In fact, 
all actual I/O tranfers are performed on full buckets only. In 
implementing protection of subsets of the file at a time, 
protection is on a bucket-by-bucket basis (bucket-locking) • 

A bucket is locked from the time any task with write access 
accesses a record in a bucket, until that task begins operations 
on another bucket, or closes the file. This means that records 
within a given bucket can't be accessed by other tasks while 
another task with write access is using the bucket. But other 
tasks may access other buckets in the file during that time. 
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Summary 

Table 9-6 summarizes our comparison of FCS and RMS. The next 
module discusses the details of how to use FCS in a program. 



Table 9-6 Comparison of FCS and RMS 



Characteristics FCS 



RMS 



Supporting 
utilities 



Standard RSX 
utilities 



Special RMS utilities 
to define, convert, 
etc . 



Supporting 
languages 



MACRO-11 

FORTRAN IV, IV-PLUS, 
-77, BASIC-11 



MACRO-11 

FORTRAN IV-PLUS, 
-77, BASIC-PLUS-2 
COBOL 



Ease of 
file design 

Ease of 
programming 



Relatively simple 



Relatively simple in 
high-level languages 



Moderate in MACRO-11 



Type of data Virtual block I/O 

access supported 

Sequential record 
access 



Relatively complex 



Relatively simple in 
high-level languages, 
issues of efficiency 
complex 

Relatively difficult 
in MACRO-11 

Virtual block I/O 

Sequential record 
access 



Random access by 
record number with 
fixed-length records 



Random access by 
cell number in a 
relative file 

Random access by 
key field within 
record, in an 
indexed file 



Access by record 
position pointers, 
saved from previous 
access of record 



Access by record 
file address, 
saved from previous 
access of record 
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Table 9-6 Comparison of PCS and RMS (Cont) 



Characteristics FCS RMS 



Overhead in file 
needed to support 
record Btructure 


Minimal 




Minimal for se- 
quential files 

Moderate for 
relative files 

High for indexed 
files 


Execution time 
overhead to 
support record 
access 


Low 




Low for sequential 
and relative files 

Moderate to high 
for indexed files, 
depending on file 
and program design, 
and file growth 


Shared access 
coordination 


System protection on 
a per-file basis or 
on an all blocks 
accessed basis 


System protection 
on per-file or 
per-bucket basis 
within a file 



Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all written problems. Check your answers against 
the provided solutions in the Tests/Exercises book. 

If you think that you have mastered the material, ask your course 
administrator to record your progress on your Personal Progress 
Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, return 
to this module for further study. 
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FILE CONTROL SERVICES 



INTRODUCTION 

The File Control Services (FCS) subsystem provides the means 
through which tasks perform I/O. In FORTRAN, calls to the FCS 
routines are made indirectly through the FORTRAN Object Time 
System (OTS) . 

While the FORTRAN programmer need not know how the the data 
structures or the various calls to the FCS subroutines are used, 
this module is presented as a brief introduction to FCS. 

The first example, illustrating how a FORTRAN program creates a 
file, also shows the MACRO code needed to perform the same 
function. 

Further examples illustrate how some of the FCS features can be 
incorporated by using the FORTRAN OPEN statement and the 
appropriate forms of the READ and WRITE statements. 

The major portion of this module contains a brief summary, with 
examples, of the FORTRAN READ, WRITE and OPEN statements and the 
various file and record types used in writing a FORTRAN program. 

The FORTRAN programmer should be aware that each of the above, 
READ, WRITE, and OPEN, are translated into FCS data structures at 
compile time, and CALLS to FCS routines at execution time. 

OBJECTIVES 

1. To choose file characteristics for a specific application 
and create files with those characteristics 

2. To write tasks which read or write data using record I/O. 



RESOURCES 

1. FORTRAN IV User's Guide 

2. FORTRAN IV-Plus User's Guide 

3. FORTRAN-77 User's Guide 
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FILE ORGANIZATION VS. RECORD ACCESS 

A clear distinction must be made between the organization of a 
file and the record access to a file. 

A file's organization refers to how the file was created via the 
keyword ORGANIZATION in the OPEN. 

The two possibilities are: 

ORGAN I Z AT I ON = ' SEQUENTIAL ' 
ORGAN I Z AT I ON = ' RELATIVE ' 

'INDEXED' is a third ORGANIZATION, but will not be discussed here. 

Once established, the file ORGANIZATION cannot be changed. The 
default is 'SEQUENTIAL'. 

The record access to a file determines how a particular program 
wants to access a file, again via the OPEN. The choices are: 

ACCESS= ' SEQUENTIAL ' 

ACCESS=» DIRECT' 

ACCESS=' APPEND' 

(ACCESS=' INDEXED' will not be discussed.) 

Figure 10-1 shows the possible combinations of ORGANIZATION and 
ACCESS. 



ORGANIZATION ACCESS 



SEQUENTIAL SEQUENTIAL 
" APPEND 
" DIRECT (if fixed 

length records) 

RELATIVE DIRECT 

" SEQUENTIAL 



Figure 10-1 Possible Combinations of ORGANIZATION and ACCESS 
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READ AND WRITE ACCESS TO A FILE 



When a file is opened via the OPEN statement, the 
the file is opened for read and write access. 
READONLY is used to restrict a program from write 
are the 'WORLD' to a file (i.e., not SYSTEM, 
which has 'WORLD' protection set to R (read) , and 
open that file without using the READONLY keyword 
open will fail. 



default is that 
The OPEN keyword 
access. If you 
OWNER, or GROUP) 
you attempt to 
in the OPEN, the 



TYPES OF RECORDS IN A FILE 

(Sometimes Referred to as 'Record Format') 

There are three types of records (record formats) possible in a 
file via the OPEN keyword RECORDTYPE: 

RECORDTYPE= ' VARIABLE ' 
RECORDTYPE= ' FIXED ' 
RECORDTYPE= ' SEGMENTED ' 

Type VARIABLE consists of variable length records where the record 
length is kept in the first two bytes of each record. 

Type FIXED consists of records all of the same length as specified 
in the RECORDSIZE keyword in the OPEN. Since the size is fixed, 
it is not kept as an extra two bytes in the record; it is kept in 
the header of the file and is available when the file is opened. 

Type SEGMENTED consists of records which contain a single logical 
record having one or more variable length records (segments) . The 
length of a segmented record is arbitrary; however, the length of 
each segment is determined by the value of the RECORDSIZE keyword. 
The default size is 133. The segmented record is unique to 
FORTRAN and can be used only with unformatted sequential files 
under sequential access. 

Because there is no set limit on the size of a segmented record, 
each segment contains control information to indicate that the 
segment is one of the following: 

• The first segment in the segmented record (control word=l) 

• The last segment in the segmented record (control word=2) 

• The only segment in the segmented record (contol word=3) 

• None of the above: i.e., a continuation record (control 
word=0) 
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The control word is kept as the first two bytes in the segment if 
the record is FIXED and in the third and fourth bytes if the 
record is VARIABLE. 

When you wish to access an unformatted sequential file that 
contains fixed length or variable length records, which was not 
created by FORTRAN, you must specify RECORDTYPE= ' FIXED' or 
RECORDTYPE=' VARIABLE' when you open the file. If you do not 
specify a RECORDTYPE, the default OPEN of the file will be 
RECORDTYPE=' SEGMENTED' and the first word (if FIXED) or the second 
word (if VARIABLE) will be treated as a control word causing 
almost certain errors in the data. 



FORMATTED AND UNFORMATTED RECORDS 

A READ or WRITE statement can be formatted or unformatted. The 
main difference in the two is that a formatted READ or WRITE uses 
ASCII data while an unformatted READ or WRITE uses untranslated 
binary data. 

The FORM= ' FORMATTED ' or FORM= ' UNFORMATTED ' is used as appropriate. 
The default is FORMATTED for ORGANIZATION^ SEQUENTIAL' and 
UNFORMATTED for ORGANIZATION= ' RELATIVE ' . 



DECLARING THE SIZE OF A RECORD 

The keyword RECORDSIZE is used to declare a specific size for a 
record. The defaults are as follows: 

FORMATTED 133 bytes 

UNFORMATTED (fixed) 128 bytes 

UNFORMATTED (variable) 126 bytes 

Note that you must specify the TKB option MAXBUF=n if you ex. -jed a 
record size of 133, where n is the size in bytes of the record. 
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SUMMARY OF KEYWORDS IN THE OPEN STATEMENT 



ORGANIZATION 
ACCESS 

READONLY 
RECORDTYPE 

FORM 

RECORDSIZE 



'SEQUENTIAL* 
1 RELATIVE 1 

' SEQUENTIAL 1 
'DIRECT 1 

'APPEND' (sequential only) 
to disallow WRITES 

'FIXED' 

'VARIABLE' 

•SEGMENTED' 

» FORMATTED ' 
' UNFORMATTED' 



n 



The remainder of this module is a series of examples illustrating 
the various types of files and how they are OPENed and ACCESSed. 
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Example 10-1, CRESEQ, creates a file, VARI.ASC, of variable length 
records. Since the records are variable in length, the byte count 
for each record is kept in the first two bytes of the record 
itself . 

As can be seen from the run session, the first record contains a 
single character, 1. Therefore bytes and 1 are 001 and 000. 
The next byte is 61, which is ASCII for 1 followed by a byte of 
000. Since the record has an odd number of bytes, the record is 
padded with a 000 byte. 

The next record contains an even number of bytes (2) , so the 
record need not be padded. 

Although the examples use several defaults, in order to illustrate 
the various defaults, it is recommended that no defaults be used 
when creating a file with an OPEN statement. Hence, in Example 
10-2, the complete OPEN is as follows: 

0PEN(UNIT=1,NAME= , VARI.ASC I , CARRIAGECONTROL= ' LIST ' , 

1 ORGANIZATION^ SEQUENTIAL 1 ,ACCESS= ' SEQUENTIAL 1 , 

2 TYPE=' NEW ,FORM=' FORMATTED' ) 

While it may seem a bit tedious to include all options in the 
OPEN, it aids greatly in the readability of the program and 
relieves any question as to what was meant in the OPEN. 
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PROGRAM CRESEQ ! CREATE FILE SEQUENTIALLY 

C 

C FILE CRESEQ ♦ FTN 
C 

C This task creates 3 file VARI*ASC of variable™ length 
C records using sequential record access* The records 
C are input from the terminal and written to the file* 
C The process stops when the operator types CTRL/Z at 
C the terminal* 
C 

BYTE BUFF(80) 
INTEGER LEN 

C OPEN FILE ~ Default access is sequential y default form 
C is formatted I/O with sequential access 

OPEN ( UNIT-l t NAME™ ' VARI * ASC ' y TYPE™ ' NEW ' y 

1 CARRIAGECONTROL~'LIST' > 

C Loop 

10 READ <5yllyEND=100> LEN y BUFF ! Read record 

11 FORMAT (QySOAl) 

WRITE (1*12) <BUFF( I ) 9 1=1 yLEN) ! Write record 
.1.2 FORMAT (80A1) ! to file 

GO TO 10 
C Close file 3nd exit 
100 CLOSE (UNITED 

CALL EXIT 

END 



Run Session 

>RUN CRESEQ 
1 

22 

333 

4444 

Now is the time for all good* 



Dump of DR2* C305'y 3013VARI *ASC?6 - File ID 40554y5y0 

Virtual block Oy 000001 - Size 512* bytes 



000000 001 000 061 000 002 000 062 062 003 000 063 063 063 000 004 000 

000020 064 064 064 064 035 000 116 157 167 040 151 163 040 164 150 145 

000040 040 164 151 155 145 040 146 157 162 040 141 154 154 040 147 157 

000060 157 144 056 000 000 000 000 000 000 000 000 000 000 000 000 000 



ample 10-1 Creating a Sequential File with Variable Length Records 
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Example 10-2 shows the equivalent MACRO code to produce the same 
file as Example 10-1. 

Example 10-3, SEQFOR, reads the first five records from the file 
VARI.ASC and displays them on the terminal. 



♦ TITLE CRESEO 

♦ I DENT /0.1/ 
* ENABL LC 



i Enable lower esse 



v File CRESEQ ♦ MAC 



CRESEO cre3tes 3 file VARI*ASC of variable- length 
records using sequential access* It reads records from 
TI*y and places them in the file* A ~Z terminates 
input and closes the file* 

Assemble and task -build instructions* 

MACRO/LIST LB* 11 1 y 1 3PR0GMACS/LIBRARY y dev * lluf d.']~ 
->CRESEQ 

LINK/MAP CRESEQ y LB ♦ CI y .1. .1PR0GSUBS/LIBRARY 



♦ MCALL 
♦ MCALL 
*MCALL 
♦ MCALL 

FSRSZ* 



EXST$CyQIOW*CyQIOW$yDIR* y Sastem macros 
FSRSZ* y FDBDF* y FDAT* A y FDRC* A y FDOP*A ? System 
NMBLK'$yOPEN*Uy PUT* y CLOSE* 9 FCS macros 
DIRERR y IOERR y FCSERR y Supplied macros 



v Define file descriptor block 



FDB i 



FDBDF* 
FDAT*A 



R*VARyFD*CR 



FDRC*A y BUFF 



FDOP*A 1 y y FNAME 



FNAME * 
BUFF : 

iost: 



NMBLK* 

♦ BLKB 
♦JBLKW 

* EVEN 

♦ ENABL 



VARIyASC 
80* 



LSB 



y 1 file for record I/O 
for VARI*ASC 

y Allocate the FDB 

y Variable length records." 

y Listing - implied 

y <CR>y<LF> 

y Sequential access and 
y record I/O by 
y default y BUFF is 
y user record buffer 

y Use LUN ly file spec 
y 3t FNAME 

y B VARI*ASC B 

y User Record Buffer 

y I/O status block 

y Enable local symbol 

y block 



Example 10-2 MACRO Equivalent of Example 10-1 (Sheet 1 of 2) 
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? Open file for write* call ERR1 if open fails 
START : OPEN*W #FDB nnn ERR1 
P Get record from terminal* put to file* 
10*: QI0W*C I0,RVBy5y1.y ylOSTy y<BUFFy80.> 

BCS ERR2D 9 Branch on directive 

y error 

TSTB I0ST ? Check for I/O error 

BLT ERR2I y Branch on I/O error 



MOV I0ST+2yRl y Number of bytes input 

PUT* ♦FDByyRl ? Put record to file 

BCS ERR3 ? Branch on FCS error 

BR 10* 5 Get next record 



EXIT J 



CLOSE* 
EXST*C 



#FDByERR4 
EX*SUC 



Error code - Close file 
messasfe and exit 



y Close file 
y Exit with success 
y status 
if necessary y display error 



ERR1 J 
ERR2D* 
ERR2I * 



E.RR3 i 
ERR 4 i 



FCSERR 
DI'RERR 
CMPB 
BEQ 

I0ERR 

CLOSE* 
FCSERR 
FCSERR 
♦ END 



♦FDB y < ERR OR OPENING FILE> 
DIRECTIVE ERROR ON READ> 



♦ IE ♦ EOF y I GST 
EXIT 

♦ I0ST y <ERRGR ON 



♦FDByERR'4 
♦FDB y <ERR0R 
♦ FDB y <ERR0R 
START 



close file 



Is it ~Z? 
If eaualy 
and exit 
"AD> 5 Display error 
y message and exit 
y Close file ' 
WRITING RECORDS- 
CLOSING FILE> 



Run Session 

>RUN CRESEQ 
J. 

22 

333 

4444 

Now is the time for all good* 



Dump of DR2J C305y3013VARI *ASC?6 •- File ID 40554y5y0 

Virtual block 0» 000001 • Size 512. bytes 



000000 001 000 061 000 002 000 062 062 003 000 063 063 063 000 004 000 

000020 064 064 064 064 035 000 .1.16 157 167 040 151 163 040 164 150 145 

000040 040 164 151 155 145 040 146 157 162 040 141 154 154 040 147 157 

000060 157 144 056 000 000 000 000 000 000 000 000 000 000 000 000 000 



Example 10-2 MACRO Equivalent of Example 10-1 (Sheet 2 of 2) 
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PROGRAM SEQFOR 

C 

C File SEQFOR *FTN 
C 

C This task reads the? first 5 records from the file 

C VARI*ASC usinsS sequential access and formatted reads* 

C It displays the records at TI*» 

C 

INTEGER REC<40> 
C Open file 

OPEN (UNIT-i^NAME^'VARI.ASC'^TYPE^'OLD') 

C ! Defaults to 

C .' seauential access y 

C ! formatted reads 

DO 100 1*1 y 5 
C Read record from file 

READ (lylO) NyREC 
.1.0 FORMAT <Qy40A2> 

C Write record at terminal 

WRITE (5y20) (REC(K) *K=1 v (N-f 1 )/2) 
20 FORMAT (' / y40A2) 

.1.00 CONTINUE 
C Close file and exit 

CLOSE (UNITED 

CALL EXIT 

END 



Run Session 

>RUN SEQFOR 
1 

22 

333 

4444 

Now is the time for all 3ood* 



Example 10-3 Program to Read File Created in 10-1 
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Example 10-4, CRESEQFIX, creates a file, FIXED. ASC, containing 

fixed length records of 16 bytes each. In a file of fixed length 

records, the size of each record is kept in the header of the file 

rather than in the first two bytes of the record itself. In the 

file dump you will see that the first input record, containing a 

1, creates a record consisting of 61 (ASCII) and 15 blanks 

(40(8)). The next record is 62, 62, and 14 blanks, etc. 

One advantage of a file of fixed length records is that the file 
may be accessed in DIRECT (or random) mode for both READ and 
WRITE. The disadvantage of a fixed length record is that, 
assuming a 16-byte record, a record containing one byte and a 
record containing 16 bytes occupies the same space on the disk. 
(Direct access is not available on a tape or cassette.) If you 
have a wide disparity in record sizes, say 10 and 80, it may not 
be practical to use fixed length records. However, where disk 
space is not a problem, using direct access to a sequential file 
might be very useful. 
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PROGRAM CRESEQFIX ! CREATE FILE SEQUENTIALLY 

C 

C FILE CRESEQFIX ♦ FTN 
C 

C This task creates 3 file FIXED *ASC of fixed- length 
C records using sequential r&covd access* The records 
C are input from the terminal and written to the file* 
C The process stops when the operator twpes CTRL/Z at 
C the terminal* 
C 

BYTE BUFF (80) 
INTEGER LEN 

C OPEN FILE - Default access is sequential* default form 
C is formatted I/O with sequential access* 

C 

OPEN < UN I T«l> NAME* ' FIXED ♦ ASC TYPE* 'NEW' > 

1 RECORDTYPE- 'FIXED ' y RECORDS I ZE-16 ) 

C Loop 

10 READ <5>11>END-100> LEN? BUFF ! Read record 

11 FORMAT (QySOAl) 

WRITE (1*12) (BUFF< I ) y I~l ?LEN) • Write record 

12 FORMAT (80A1) ! to file 
GO TO 10 

C Close file and exit 
100 CLOSE (UNIT-1) 

Of"kL**L» fc.XI*F 

END 



Run Session 



1 

4444 

Now is the time for all good* 



Dump of DR2:C305y30iaFIXED*ASC?3 - File ID 40573*6*0 

Virtual block Or 000001 - Size 512* bwtes 



000000 061 040 040 040 

000020 062 062 040 040 

000040 063 063 063 040 

000060 064 064 064 064 

000100 122 157 163 145 



040 040 040 040 040 040 
040 040 040 040 040 040 
040 040 040 040 040 040 
040 040 040 040 040 040 
.163 040 141 162 145 040 



040 040 040 040 040 040 
040 040 040 040 040 040 
040 040 040 040 040 040 
040 040 040 040 040 040 
162 145 144 056 040 040 



Example 10-4 Creating a File With Sequential, 
Fixed Length Records 
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Example 10-5, READFIXED, prompts you for the record number of the 
record you want from the file FIXED. ASC, displays the record and 
then allows you to replace the record if you wish. Note that the 
file was created as a sequential file with fixed length records 
and is being accessed as DIRECT. Since the record size is in the 
header of the file, it is not necessary to describe the record 
size in the OPEN. Note that both the READ and the WRITE to unit 1 
use the formatted, direct form, i.e.: 

READ (1*NO,10) 

and 

WRITE (l'NO,10) 

One precaution here is that if you attempt to replace a record 
with a longer record (in this case 16 bytes) than the original, 
the new record will be truncated on the right. 

As you can see from the run session in CRESEQFIX, the third record 
originally contained 333. This was replaced with "Now is the 
Time", as is shown by running READFIXED a second time and 
displaying record 3 again. 
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FILE CONTROL SERVICES 



PROGRAM READFIXED 

C 

C File READFIXED *FTN 

c 

C This task asks you which record you want from FIXED ♦ ASC y 
C and displays the record on the terminal* It then asks if 
C you wish to replace the record and if so asks for the new 
C record* 
C 

CHARACTER*16 RECyNEW 
C Open file 

OPEN (UN1'T~1 y NAME™ "FIXED* ASC y TYPE™ ' OLD " y ACCESS-- ' DIRECT ' y 
1 FORM" ' FORMATTED ' ) 
C Read record from file 

TYPE *y "Enter record number you want*' 
READ *yNO 

READ (l'NOrlO)REC ! Get record number NO 
10 FORMAT <A16) 

C Write record at terminal 

WRITE (5y20) REC 

TYPE *y 'Do you want to replace the record? Y or N ' 
READ(5y 10) ANS 

IF ( ANS ♦ EG ♦ ' N ' ♦ OR ♦ ANS * EQ ♦ ' n ' ) GO TO 100 

TYPE *y 'Enter new record*' 

READ ( 5 » 10) NEW 
20 FORMAT (' "yA16) 

WRITEd ' NO y 10) NEW 
100 CONTINUE 
C Close file and exit 

CLOSE (UNIT-l) 

CALL EXIT 

END 



Run Session 
>RUN READFIXED 

Enter record number you want* 
3 

333 

Do you want to replace the record? Y or N 
Y 

Enter new record* 
Now is the time* 
>RUN READFIXED 

Enter record number you W3nt* 
3 

Now is the time* 



Example 10-5 Reading a Fixed Length Record 
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FILE CONTROL SERVICES 



Example 10-6, DIRFOR, illustrates the creation of a file via 
direct access. The example creates record 1 through record 5, in 
order. It is not necessary to create the records in order, nor 
must there be a record n-1 if record n exists. Hence you may have 
a sparse file, containing only those records whose record numbers 
are specifically used in a WRITE. 

Note that the RECORDSIZE = 10 is used in the OPEN. Since this is 
a formatted record, the recordsize of 10 means that each record 
will be 10 bytes. Hence the first record, containing 1,1,1,1,1, 
is filled with five blanks (40,40,40,40,40). The fifth record, 
which contains just a 5, is filled with nine blanks. The rest of 
the file is filled with zeros. 
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FILE CONTROL SERVICES 



PROGRAM DIRFOR 

C 

C File DIRFOR. FTN 
C 

C This task creates 3 file DIRFOR ♦ DAT using direct 

C access formatted writes* 

C 

C Direct access formatted writes are available in 

C FORTRAN IV-PLUS and FORTRAN -77 onlw 

C 

INTEGER REC(IO) 

C 

C Open file 

OPEN < UN I T=2r NAME* 'DIRFOR. DAT '» ACCESS* 'DIRECT ' 1 

1 TYPE™ 'NEW v FORM™ ' FORMATTED ' t RECORDS I ZE* 1 ) 

DO 100 1*1,5 
C Prompt for input 

WRITE <5i>25) 
25 FORMAT <'* INPUT UP' TO 10 DIGITS * ') 

C Read record from terminal 

READ <5»50>N,REC 
50 FORMAT <Q»10I1) 

C Write record to disk 

WRITE (2' 1*80) <REC<K)»K*1,N> 
BO FORMAT (1011) 

100 CONTINUE 

CLOSE (UNIT=2) 

CALL EXIT 

END 



Run Session 

>RUN DIRFOR 
INPUT UP TO 
INPUT UP TO 
INPUT UP TO 
INPUT UP TO 
INPUT UP TO 



10 digits: 
10 digits: 
10 digits: 
10 digits: 
10 digits: 



11111 
2222 

3333333333 
444 

b 



Dump of DR2tC 305 ,30 ID DIRFOR. DAT J 17 - File ID 40653,10,0 

Virtual block Oy 000001 - Size 512. bytes 



000000 061 061 061 061 061 040 040 

000020 040 040 040 040 063 063 063 

000040 064 040 040 040 040 040 040 

000060 040 040 000 000 000 000 000 



040 040 040 062 062 062 062 040 040 

063 063 063 063 063 063 063 064 064 

040 065 040 040 040 040 040 040 040 

000 000 000 000 000 000 000 000 000 



Example 10-6 Creating a Direct Access File 
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FILE CONTROL SERVICES 



Example 10-7, DIRUNF, creates a file with unformatted, direct 
access records. Since the file is unformatted, the record size of 
5 does not refer to five bytes but rather to five storage units 
where a storage unit is defined as four bytes. Hence each record 
is 20 bytes long. Note that the file dump shows words rather than 
bytes. This is because the data type is INTEGER which has two 
bytes for each value. The first record contains five words of 
00001 padded with five words of 00000 to pad out the 20-byte 
record. 
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FILE CONTROL SERVICES 



PROGRAM DIRUNF 

C 

C File DIRUNF ♦ FTN 
C 

C This t3sk creates a file DIRUNF* DAT usina direct 

C access unformatted writes* 

C 

INTEGER RECC10) 
C Open file 

OPEN ( UNIT"4 y NAME" ' DIRUNF * DAT ' y ACCESS" 'DIRECT ' y 

1 TYPE™ ' NEW ' y RECORDSIZE-5 ) ! Defaults to 
C ! unformatted 

DO lOOy I~ly5 
C Prompt fpr input 

WRITE <5»25) 
25 FORMAT <' INPUT UP TO 10 DIGITS:') 

C Read record from terminal 

READ <5yl0> NyREC 
10 FORMAT (QylOIl) 

C Write record to disk 

WRITE <4'I) (REC(K') yK~lyN) 
.1.00 CONTINUE 

CALL EXIT 

END 



Run Session 
>RUN DIRUNF 
INPUT UP TO 
INPUT UP TO 
INOUT UP TO 
INPUT UP TO 
INPUT UP TO 



10 digits: 
:i.o digits: 
io digits: 
io digits: 
io digits: 



mi i 

222? 

3333333333 
444 

5 



Dump of DR2 : 1 305 y 30 ill DIRUNF* DAT? 13 •••• File ID 40661 y5y0 

Virtual block 0*000001 - Size 512* bytes 



000000 
000020 
000040 
000060 
000100 
000120 
000140 



000001 
000000 
000000 
000003 
000004 
000005 
000000 



000001 
000000 
000000 
000003 
000000 
000000 
000000 



000001 
000002 
000000 
000003 
000000 
000000 
000000 



000001 
000002 
000000 
000003 
000000 
000000 
000000 



000001 
000002 
000003 
000003 
000000 
000000 
000000 



000000 
000002 
000003 
000003 
000000 
000000 
000000 



000000 
000000 
000003 
000004 
000000 
000000 
000000 



000000 
000000 
000003 
000004 
000000 
000000 
000000 



Example 10-7 Creating an Unformatted, Direct Access File 



FILE CONTROL SERVICES 



Example 10-8, SEQUNF, illustrates the SEGMENTED record type, even 

though the OPEN does not contain RECORDTYPE = 'SEGMENTED*. This 

is because SEGMENTED is the default record type for an 

UNFORMATTED, SEQUENTIAL file. This is the default file type 

created by an unformatted WRITE in FORTRAN. Hence, if there had 
been no OPEN statement, and the write statement was as shown: 

WRITE(l) (REC(K) ,K=1,N) 

the file created would default to FOR001.DAT (001 because 1 was 
used in the WRITE) and the record type would be SEGMENTED. The 
advantage of a file with segmented records is that there is no 
limit to its size, i.e., a single record could be many physical 
blocks on a disk. The disadvantage of a file with segmented 
records is that it cannot be read by any other high level 
languages. 
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FILE CONTROL SERVICES 



PROGRAM SEQUNF 

C 

C This task creates s file SEQUNF* DAT using seauential 
C unf orm3tted writes 

c; 

BYTE RECQO) 

c 

Open file 

OPEN < UNIT-1 f NAME-- ' SEQUNF ♦ DAT ' y TYPE-"-' 'NEW y 

1 FORM- ' UNFORMATTED ' y ACCESS- ' SEQUENTIAL ' ) 
C Loop for 5 records 

DO 100 I~l»5 
V, Prompt for input 

WRITE <5>25> 
25 FORMAT <'* INPUT UP TO 10 DIGITS * ') 

C Re3d record from terminal 

READ <5v50) N y REC 
'50 FORMAT (QylOIl) 

C Write record to disk 

WRITE (1) (REC(K)»K=1»N) 
100 CONTINUE 

CLOSE (UNIT"1) 

CALL EXIT 
C Error routine 
900 WRITE <5y950) 

950 FORMAT (' THERE WAS A FILE OPEN ERROR") 

CALL EXIT 
END 



Run Session 



>RUN SEQUNF 
INPUT UP TO 
INPUT UP TO 
INPUT UP TO 
INPUT UP TO 
.INPUT UP TO 



10 digits: 

10 DIGITS i 

10 digits: 

10 digits: 

10 digits: 



1 1 11 1 
22^2 

3333333333 

444 

5 



Dump of DR2:C305'y3013SEQUNF»DATyl6 ~ File ID 40675y3y0 

Virtual block Oy 000001 -•• Size 512* bates 



000000 000014 000003 000001 

000020 000003 000002 000002 

000040 000003 000003 000003 

000060 000003 000010 000003 

000100 000005 000000 000000 



000001 000001 000001 000001 000012 

000002 000002 000026 000003 000003 

000003 000003 000003 000003 000003 

000004 000004 000004 000004 000003 
000000 000000 000000 000000 000000 



Example 10-8 Creating a Segmented File 
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FILE CONTROL SERVICES 



Example 10-9, FWRITE, illustrates how a Block I/O routine written 
in MACRO can be called by a FORTRAN program. Block I/O is not 
directly available in FORTRAN. 



♦TITLE FWRITE 
♦ I DENT /O.1./ 
♦ENABL LC 



P Enable lower esse 



P FWRITE is 3 FORTRAN -cal lable block I/O subroutine* 
P 

r Subroutine call* 
P 

9 CALL FWRITE ( i lun y ibuf 9 isiz y i vb y ief n 9 iosb 9 ier r ) 



P 


where ilun 


is 


logical unit number 


P 


ibuf 


is 


block buffer address 


9 


i s i z 


is 


block buffer size <in bytes) 


P 


i vb 


is 


3ddress of 2~wo rd v»b» number 


P 


ief n 


is 


event flas$ 


P 


iosb 


is 


I/O ststus block 


P 


i err 


is 


a ststus code 


P 




+ 1 


- Success 


P 




-1 


*FCHNL ERROR 


? 






CANNOT CHANGE RECORD ACCESS 


P 




-4 


WRITE* REJECTED 



♦MCALL 
IOSB ♦ *BLKW 
P 

FWRITE ♦ ♦ 

MOV 
MOV 

CALL 

BCS 

ADD 

FDRC$R 
BCS 

WRITE* 

BCS 
MOV 

RETURN 
ERROR J. ♦ MOV 

RETURN 
ERR0R2 ♦ MOV 

RETURN 
ERR0R3 ♦ MOV 

RETURN 
♦ END 



WRITE** FDRC*R P System FCS macros 



§2(R5) yR2 
@#*0TSVyR3 

*FCHNL 
ERROR 1 
#14yR0 
y#FD*RWM 

ERR0R2 

y4(R5) y@6(RS) 

ERROR 3 
#ly@16(R5) 

#-ly@16(R5) 



#-~2y(?16(R5) 



#~4yG?16(R5> 



5 Lun 

y Address of FORTRAN 

P work area 

P Get FORTRAN FDB 

? Branch on error 

P Point to FCS FDB 

? Ch3n£e record access 

? to block I/O 

P Branch on error 
ylO(R5) y@12<R5) yl4(R5) y#0 

P Issue write 

P Branch on error 

? Return success code 



Return 
code 



FCHNL failure 



9 Return couldn't change 
9 access code 

? Return write rejected 
9 code 



Example 10-9 Creating a File Using Block I/O (Sheet 1 of 3) 
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FILE CONTROL SERVICES 



PROGRAM BLOCK1 

C 

C File BLOCK1 *FTN 
C 

C BLQCK1 creates a file BLOCK ♦ ASC using FWRITEy a 
FORTRAN callable subroutine .written in MACRO-11* 
C 

C Subroutine call* 
C 



C CALL FWRITE( i luny ibuf f y isizey ivbny ief n> iosby ierr ) 
C 

C where ilun is the logical unit number 

C ibuff is the array to be written 

C i size is the size of the buffer (bytes) 

C ivbn is a 2*- integer vbn < high y low) 

C iefn is an event flag number 

C iosb is a 2~ integer I/O status block 

C ierr is an status coder 

C +1 * SUCCESS 

C -i * $FCHNL ERROR 

C ™2 * CANNOT CHANGE RECORD ACCESS 

C -4 * WRITE* REJECTED 

C 

C Task-build instructions* 
C 

C >L INK/MAP/CODE * FPP BLOCK 1 1 FWRITE y LB X IT .1. y 1 3F4P0TS- 

C -OVLIBRARY 



C 

INTEGER WDBUFF(256) t IVBN(2) 
INTEGER I S 1* ZE y I EFN y I OSB ( 2 ) y I ERR 
BYTE IOST < 2 ) y CHAR t CHBUFF ( 53.2 ) 

C 

EQUIVALENCE (lOSBylOST) ! For accessing I/O status 
EQUIVALENCE ( WDBUFF y CHBUFF ) ! For accessing data 
DATA ILUNy ISIZEy IEFN /.Ly512y2/ 
C Get virtual block # 
TYPE 5 

5 FORMAT <'$VIRTUAL BLOCK NUMBER (LOW ONLY): ') 
ACCEPT 6y IVBN (2) 

6 FORMAT <I6) 

IVBN(l) « ! High VBN * 

C Get character to insert 
TYPE 7 

7 FORMAT ( '^CHARACTER* ') 
ACCEPT 8 y CHAR 

FORMAT (IAD 
C Fill buffer with character 

DO 9»I=1»ISIZE 

9 CHBUFF(I) " CHAR 



Example 10-9 Creating a File Using Block I/O (Sheet 2 of 
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FILE CONTROL SERVICES 



C Open file 

OPEN < UNI T=- ILUN * NAME- ' BLOCK ♦ ASC ' * TYPE - ' NEW ' ) 
C C3II subroutine to write block of data 

CALL FWRITE ( ILUN * WDBUFF * ISIZE * I VBN * IEFN * IOSB * 
II ERR) 

IF (I ERR .LT* 0) GOTO 200 
TYPE 20 

20 FORMAT (' 1 BLOCK BEING WRITTEN TO FILE") 

C Wait for write to complete 

CALL WAITFR( IEFN* IDSW) 

IF (IDSW *LT. 0) GOTO 40 ! Check for dir error 

IF (I0ST(1) *LT* 0) GOTO 100 ! Cheek for I/O 
C ! error on write 

WRITE (5*30)I0SB(2) 
30 FORMAT (' WRITE COMPLETED * ' 9 16 9 ' BYTES WRITTEN 

1T0 FILE') 

GOTO 300 

C 

40 TYPE 45' 9 IDSW 

45 FORMAT (' DIRECTIVE ERROR* IDSW = '*I6) 

GOTO 300 

C 

100 WRITE (5*110) I0ST(1) 

110 FORMAT (' I/O ERROR ♦ I/O STATUS * '*I6) 

GOTO 300 

C 

200 TYPE 210*IERR 

210 FORMAT (' FCS ERROR 9 CODE « '*I6) 

C 

300 CLOSE (UNIT=ILUN) 

CALL EXIT 
END 



Run Session 
>RUN BLOCK! 

VIRTUAL BLOCK NUMBER (LOW ONLY) t 2 
CHARACTER e 

1 BLOCK BEING WRITTEN TO FILE 

WRITE COMPLETED 9 512 BYTES WRITTEN TO FILE 

Dump of DR2:C305*30i:iBL0CK.ASC*-14 - File ID 40701*2*0 

Virtual block 0*000001 - Size 512. bytes 

Contains whatever was previously in that block on the disk 

Dump of DR2:C305*301.1BL0CK*ASC514 ~ File ID 40701*2*0 

Virtual block 0*000002 - Size 512* bytes 

000000 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 
000020 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 
000040 145 145 145 145 145 145 145 145 145 145 145 145 145 145 .145 145 



000760 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 

Example 10-9 Creating a File Using Block I/O (Sheet 3 of 3) 
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APPENDICES 



APPENDIX A 
GLOSSARY 



ASYNCHRONOUS SYSTEM TRAP (AST) - A system condition which occurs 
as a result of a specified event such as completion of an I/O 
request. 

On occurrence of the event, control passes to an AST service 
routine, and the AST is added to an Executive first-in first-out 
queue for the task in which the service routine appears. 

ATTACH - Device: Dedicate a physical device unit for exclusive 
use by the task that requested attachment. 

A task attaches a given device by issuing a QIO directive, or QIO 
and WAIT directive, specifying the I/O function 10. ATT. 

Region: Include a region in a task's logical address space. 

A task attaches a region by issuing an Attach Region directive or 
by being the target of another task's Send-By-Ref erence directive. 

CLUSTER LIBRARIES - A special setup with shared resident libraries 
which permits a task to use the same virtual address window to map 
several difficult libraries. For example, the resident FORTRAN 
Object Time System and the resident FCS libra'ry could use the same 
virtual addresses. The run-time routines map and remap the 
regions as they are needed, somewhat similar to what happens with 
regular memory-resident overlays. 

DATASET DESCRIPTOR - A six-word area in the user task containing 
sizes and addresses of ASCII data strings, which FCS consults in 
order to obtain a run-time file specification. 

A dataset descriptor for a given file is a user-created data 
structure which contains a file specification for that file. 

When the filename block associated with a given file does not 
contain sufficient information to enable FCS to do run-time file 
processing on that file, FCS tries to get the needed information 
from the file's dataset descriptor, if specified. Otherwise, FCS 
consults the file's default filename block, if specified, in order 
to get the desired information. 

DEFAULT FILENAME BLOCK - An area in the user task that supplies 
FCS with those default values that are needed to build a routine 
file specification. 
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When the filename block associated with a given file does not 
contain sufficient information to allow FCS to process the file, 
and when a dataset descriptor does not contain the needed 
information, then FCS consults the default filename block 
associated with the file to obtain the missing information. 

A default filename block may be used to supply a default name, 
extension, and/or version for the file. The MACRO programmer uses 
the NMBLK$ macro to create this block at assembly time. 

DETACH - Device: Free an attached physical device unit for use by 
tasks other than the one that attached it. 

A physical device unit can only be detached by means of an IO.DET 
I/O function issued by the task that attached it, or by the 
Executive, if the task is terminated with the device still 
attached. 

Region: Remove a region from a task's logical address space. 

A task detaches a region by issuing a Detach Region directive or 
by exiting. 

DIRECTIVE STATUS WORD - A word in the user task header into which 
the Executive returns status information about the most recently 
called directive. 

After processing a directive, the Executive passes the status of 
that directive to the issuing task by putting a success or error 
code into the task's Directive Status Word, which is assigned the 
global label $DSW. If $DSW is negative, the Executive rejected 
the directive; if $DSW is +1, the directive was successful. 

EVENT FLAG - A software flag which can be specified in a program 
request to indicate to the issuing task which of several specified 
events has occurred. 

There are 96(10) event flags. 

Event flags 1 - 32(10) are local 

33(10) - 64(10) are system global flags 
65(10) - 96(10) are group global flags 

Local flags are used for intra-task synchronization, while group 
global and system global flags are used for inter-task 
synchronization and communication. 

EXECUTIVE DIRECTIVE - A program request for Executive services. 
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An Executive directive is issued from a FORTRAN program by calling 
a subroutine in the system object library. It is issued from a 
MACRO-11 program by invoking a macro in the system macro library. 

FILE DESCRIPTOR BLOCK (FDB) - The tabular data structure which 
provides FCS with information needed to perform I/O operations on 
a file. 

A task must allocate, through calls to the FDBDF$ macro, or 
dynamically through the use of run-time macros. 

FILE STORAGE REGION (FSR) - The area in user task which FCS uses 
"to buffer all virtual blocks read or written during record, 
processing. 

FCS requires one FSR block buffer for each file to be opened at 
the same time for record I/O. When the task requests a record 
that is not in the FSR buffer, FCS reads a virtual block from the 
file into the task's file storage region. On the other hand, FCS 
writes virtual blocks in the file storage region to the file when 
a record must be put to the file. 

The user task allocates this area by issuing an FSRSZ$ macro. 

FILENAME BLOCK - The part of a file's File Descriptor Block which 
FCS uses for building, and later using, a file specification. 

The filename block contains the file's UFD, name, extension, 
version number, device name, and unit. When a file is initially 
opened, FCS fills in the filename block from user-supplied 
information in the dataset descriptor and/or default filename 
block. 

I/O STATUS BLOCK - A two-integer array which receives success or 
error codes on completion of an I/O request. If an I/O status 
block has been specified in an I/O request, the Executive clears 
both words when the I/O operation is queued. On completion, the 
low byte of the first word contains +1 if the I/O was successful, 
and a negative error code otherwise. 

If the I/O function involved a transfer, the second word contains, 
on completion, the number of bytes transferred. 

LOGICAL ADDRESS SPACE - The set of all physical addresses to which 
a task has access rights. 

If a task is running on a mapped system that includes support for 
the memory management directives, it may issue directives in order 
to manipulate its logical address space at run time. 
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LOGICAL BLOCK - A 512(10) 
block addressable volume. 



byte (256(10) word) block of data 



on 



a 



To achieve device independence, each block addressable volume is 
organized into logical blocks, numbered to n-1, where n is the 
number of logical blocks on the volume. 

The mapping of logical blocks to physical blocks is handled by the 
driver. 

LOGICAL UNIT NUMBER (LUN) - A number associated with a physical 
device unit during a task's I/O operations. 

The association of a LUN in a task with a given physical device 
may be done by the Task Builder, by the operator using the 
REASSIGN command, or at run time by the task, by issuing an Assign 
LUN directive. 

RANDOM ACCESS - A method of I/O to disk files in which records (or 
virtual blocks) are specified by record (or virtual block) number. 

Under ,FCS, a file must be organized into fixed length records in 
order for a task to do random access to the file. 

FCS supports the use of block I/O, in which virtual blocks are 
read from, or written to, the file without regard for the 
structure of those blocks. The FORTRAN language does not support 
block I/O. 

READ/WRITE MODE - An FCS file access method in which the user task 
uses the READ$ and WRITE$ macros to do block-structured I/O to a 
file. 

REGION - An area consisting of one or more contiguous 32. -word 
blocks of physical memory. 

A region may be named or unnamed, but is always assigned a unique 
region ID. A region has an associated protection word which 
specifies the access rights a task may have with respect to that 
region. Any task that satisfies the region protection word may 
attach a named region, but no task can attach an unnamed region 
unless the task has the region ID. 

RESIDENT COMMON - A shared region which contains data. 

RESIDENT LIBRARY - A shared region containing subroutines and/or 
functions. 

SEQUENTIAL ACCESS - A mode of record access in which the n+lth 
record in the file is processed after the nth record in the file. 
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Each record is assigned a record number, and each successive GET 
or PUT causes the record number to be incremented. 



SYNCHRONOUS SYSTEM TRAP (SST) - 
typically occurs as a result 
executing task. 



A "software interrupt" which 
of an error or fault within the 



On recognition of an SST, the Executive aborts the task, unless 
there is an SST vector table to an SST routine in the task. 

VIRTUAL ADDRESS - A 16-bit address which may be directly specified 
using one of the general purpose registers. 

A task specifies a virtual address whenever it uses one of the 
addressing modes in executing an instruction. Up to 32K virtual 
word addresses may be specified by a task. 

On a mapped system, the memory management hardware dynamically 
maps virtual addresses to real physical addresses. 

VIRTUAL ADDRESS WINDOW - A contiguous chunk of a task's virtual 
address space. 

Each virtual address window in a task begins on a 4K word boundary 
and consists of one or more 32(10) word blocks of virtual address 
space. Each window has a unique number assigned to it by the 
Executive. Window always maps the task's header, stack, and 
code. A task may divide its virtual address space into eight 
windows . 

VIRTUAL BLOCK - One of the logical blocks belonging to a file. 

Each file consists of one or more logical blocks. The logical 
blocks belonging to a file are called virtual blocks 1, 2, 3, etc. 
The mapping of virtual blocks in a file to logical blocks on disk 
is performed by the file system. 

WINDOW DESCRIPTOR BLOCK (WDB) - A data structure used in a task in 
order to represent a dynamically created window. 
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APPENDIX B 
CONVERSION TABLES 



Table B-l Decimal/Octal f Word/Byte/Block 


Conversions 


Words (10) /Words (8) Bytes (10) /Bytes (8) Blocks (10) /Blocks (8) 


1/1 1/ I 




32/40 64/100 


1/1 


IK =1024/2000 2048/4000 


32/40 


2K =2048/4000 4096/10000 


64/100 


4K =4096/10000 8192/20000 


128/200 


8K =8192/20000 16384/40000 


256/400 


16K =16384/40000 32768/100000 


512/1000 


32K =32768/100000 65536/200000 


1024/2000 


64K =65536/200000 131072/400000 


2048/4000 


128K=131072/400000 262144/1000000 


4096/10000 


Table B-2 APR/Virtual Addresses/Words Conversions 


APR Virtual Addresses 


Words 


000000-017776 


0-4K 


1 020000-037776 


4-8K 


2 040000-0.57776 


8-12k 


3 060000-077776 


12-16K 


4 100000-117776 


16-20K 


5 120000-137776 


20-24K 


6 140000-157776 


24-28K 


7 160000-177776 


28-32K 
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APPENDIX C 
FORTRAN/MACRO- 11 INTERFACE 

CALLING A MACRO- 11 SUBROUTINE FROM A FORTRAN PROGRAM 

FORTRAN Program Call: 

CALL SUBNAM (I,J f K) 
MACRO translation: 

1. Set up table of arguments. 





Count 


= 3 


Address of 


I 


Address of 


J 


Address of 


K 



2. Issue subroutine call. 

JSR PC, SUBNAM 
or 

CALL SUBNAM 
The FORTRAN Callable MACRO-11 Subroutine 
; Accessing: 

; Argument count = (R5) 

Argl = @2(R5) 
; Arg2 = @4(R5) 

j Arg3 = @6(R5) 

SUBNAM: : 

RTS PC ; or RETURN 
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CALLING A FORTRAN SUBROUTINE FROM A MACRO- 11 PROGRAM 



In the MACRO program: 



LINK: 



.BYTE 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 



3,0 



A: 
B: 
C: 



A 
B 
C 
2 
3 




MOV 
JSR 



#LINK,R5 
PC, SUB 



In the FORTRAN program: 



SUBROUTINE SUB (L,M,N) 

N=L+M 

RETURN 

END 

NOTE 

This method is also used to call a FORTRAN 
callable subroutine (written in MACRO-11) . 



Example 7-3 in the Static Regions module shows a shareable library 
LIB. MAC, which contains FORTRAN callable subroutines. USELIB.MAC, 
also in Example 7-3, shows a referencing task which calls 
subroutines in the library. 



376 



APPENDIX D 
PRIVILEGED TASKS 



RSX-11M systems have two classes of tasks, privileged and 
nonpr ivileged . The basic difference is that privileged tasks have 
certain system-access capabilities that nonpr ivileged tasks do not 
have. These privileges include one or more of the following: 

• Access to Executive routines and data structures 

• Automatic mapping to the I/O page 

• Bypass of system security features. 

NOTE 

Privileged tasks may be hazardous to a run- 
ning system. 

Use one of the following qualifiers (switches) to build a 
privileged task. 

1. /PRIVILEGED qualifier (MCR /PR:0) 

This task is built in the same way as a nonpr ivileged task 
and does not map to the Executive or the I/O page. It 
can, however, do the following: 

• Bypass file protection 

• Issue directives which require privileges (e.g., Alter 
Priority, QIO for Write Logical Break-through) 



• Issue QIOs to write logical blocks to a mounted 
volume, regardless of who issued the MOUNT or ALLOCATE 
command . 



2. /PRIVILEGED or /PRIVILEGED (MCR /PR:4 or /PR:5) 



This task has the privileges of a /PRIVILEGED task, plus 
it maps to the Executive and the I/O page. The user task 
code is mapped beginning at APR 4 or 5, as specified. The 
APRs below the one specified are used to map to the 
Executive, and APR 7 is used to map the I/O page. Use 
/PRIVILEGE : 4 if the Executive is 16K words or less; use 
/PRIVILEGE: 5 if the Executive is between 16K and 20K 
words. If the task code extends beyond the end of the 
addresses mapped by APR 6, then APR 7 is used to map the 
excess code, and the task does not map to the I/O page. 

Privileged tasks are discussed in detail in the RSX-11M Internals 
Course. See also Chapter 6 on Privileged Tasks in the 
RSX-11M/M-PLUS Task Builder Manual. 
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APPENDIX E 

TASK BUILDER USE OF PSECT ATTRIBUTES 

The Task Builder collects scattered occurrences of program 
sections of the same name and combines them in a single area in 
your task image. The program section attributes control how the 
Task Builder collects and places each program section. 

See Chapter 2 of the RSX-11M/M-PLUS Task Builder Manual for a 
complete discussion of program section attributes. 

Example of allocation code attributes: 

CON (concatenate) versus OVR (overlay) 

1. A. OBJ has Psect Q,CON - length 100(10) words 
B.OBJ has Psect Q,CON - length 50(10) words 
When task-built: 

LINK A,B 

Yields 150(10) words in Psect Q 

(first A's 100(10) words, then B's 50(10) words). 

2. A. OBJ has Psect Q,OVR - length 100(10) words 
B.OBJ has Psect Q,OVR - length 50(10) words 
When task-built: 

LINK A,B 

Yields 100(10) words in Psect Q 

(A's 100(10) words. B's 50(10) words are the 

same as A's first 50(10) words). 
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Example of scope code attributes: 

LCL (local) versus GBL (global) 

Overlay Tree B.ODL file: 

B3 
I 

Bl B2 .ROOT B-* ! (Bl , B2-B3) 

| 1 • END 

B 

Task-build command (for all): LINK B/OVERLAY DESCRIPTION 

1. B.OBJ has Psect Q, LCL , CON - length 100(10) words 
Bl. OBJ has Psect Q, LCL, CON - length 50(10) words 
When task-built: 

Yields 100(10) words in Psect Q in root segment B 
Yields 50(10) words in Psect Q in overlay segment Bl 

2. B.OBJ has Psect Q, GBL, CON - length 100(10) words 
B1.0BJ has Psect Q, GBL, CON - length 50(10) words 
When task-built: 

yields 150(10) words in Psect Q in root segment B (in the 
segment closest to the root); B's 100(10) words, then 
Bl's 50(10) words. 

If GBL, OVR instead, yields 100(10) words in Psect Q in the 
root segment. B's 100 words, with Bl's 50(10) words the 
same as B's first 50(10) words. 
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3. B2.0BJ has Psect Q (LCL or GBL) - length 100(10) words 
B3.0BJ has Psect Q (LCL or GBL) - length 50(10) words 
When task-built: 

If CON, yields 150(10) words in Psect Q in overlay segment 
B2 (allocation collected, since it is all in the same 
overlay segment). 

If OVR instead, 100(10) words in Psect Q in overlay 
segment B2. B3's 50(10) words are the same as B2's first 
50 (10) words. 

LCL and GBL are used only for overlaid tasks. In a non-overlaid 
task or within an overlay segment in an overlaid task, allocations 
are collected when either LCL or GBL is specified, as in Example 
3. 

Example of FORTRAN COMMONS at Psects: 

Psect attributes are always: RW,D,GBL,OVR,REL 

COMMON /RDATA/ 1(100) 
Macro translation: 

.PSECT RDATA, RW,D, GBL, OVR, REL 
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APPENDIX F 

ADDITIONAL SHARED REGION TOPICS 



SHARED REGIONS WITH OVERLAYS 

• Can be referenced using a smaller window in referencing 
task 

• Reuse virtual addresses in the referencing task 

• Must be memory-resident overlays 

• Have overlay structures which are placed in the .STB file 
and later placed in root segment of referencing task. 



BUILDING A RESIDENT LIBRARY WITH OVERLAYS 

1. Code and assemble library modules. 

2. Write regular . ODL file to define overlay structure. 

• Typical structure has a null root. 

3. Task-build as a shared region. 

• Only symbols defined or referenced in the root are 
included in the .STB file. 

• Force inclusion of global references into root, when 
necessary, using GLBREF option. 

Example .ODL file OVRLIB.ODL (Figure F-l) : 

.NAME OVRLIB 

.ROOT OVRLIB-*! (H r I-J) 

. END 



Example task-build command: 

>LINK/NOHEADER/MAP/ SYMBOL_T ABLE/OPTIONS OVRLIB/OVERLAY- 

->_DESCRIPTION 

Option? STACK=0 

Option? PAR=OVRLIB:140000:40000 
Option? GBLREF=H , I , J 
Option? <RET> 
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Referencing task is created using regular procedure to reference 
library OVRLIB. 

See section 5.1.4 (on Shared Regions with Memory-Resident 
Overlays) in the RSX-11M/M PLUS Task Builder Manual for additional 
information. 

PHYSICAL 
MEMORY 



VIRTUAL 
MEMORY 



160000 APR 7 




APRO 



Figure F-l A Shared Region With Memory-Resident Overlays 
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REFERENCING MULTIPLE REGIONS IN A TASK 

• Use the usual procedure if: 

The number of available APRs in the referencing task 
is sufficient 

Shared regions are logically independent (one library 
does not call the other library) 

• If shared regions are built absolute, APRs (and virtual 
addresses) cannot overlap. 

Example task-build for logically independent libraries (Figure 
F-2): 

Libraries: ARES built absolute at V.A. 160000(8); length 4K 

words 

BRES built absolute at V.A. 120000(8); length 6K 
words 

Referencing task: REF 

> LINK/MAP/OPTIONS REF 
Option? RESLIB=ARES/RO 
Option? RESLIB=BRES/RO 
Option? <RET> 
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160000 APR 7 
140000 APR6 _ 
120000 APR 5 



100000 APR 4 




60000 APR3 L 
40000 APR 2 
20000 APR1 
APRO 



VIRTUAL 
MEMORY 

TASK REF 



ARES 

(4K WORDS) 



#UNUSED/ 



BRES 

(6K WORDS) 



UNUSED 




REF 

I16K WORDS) 



/ 

/ 

/ 
/ , 

-// 

/ 

/ 

/ 



PHYSICAL 
MEMORY 



BRES 



ARES 



REF 



Figure F-2 Referencing Two Resident Libraries 
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INTERLIBRARY CALLS 

One library can call another library 

FORRES calls FCSRES 

To build libraries with interlibrary calls, use any of these 
techniques . 

• Build as a single combined library, then build referencing 
task (Figure F-3) . 

• If referenced library does not contain overlays (Figure 
F-4) : 

Build referenced library. 

Build referencing library, specifying referenced 
library to resolve calls. 

Build referencing task, specifying only referencing 
library. 

• If referenced library has overlays (Figures F-5 and F-6) : 

You must revector interlibrary calls to allow access 
to overlay structure and autoload vectors (always in 
root of referencing task) . 

Once revectoring is included, build shared regions and 
referencing task as if regions are logically 
independent. 

Example task-build commands for each technique follow. 

Example task-build command for combined libraries (Figure F-3) : 

>LINK/MAP/NOHEADER/ SHAREABLE : LIBRARY/SYMBOL_TABLE- 
->/OPTIONS F4PRES , LB : [1,1] F 4 POTS/LIBRARY 
Option? STACK=0 

Option? PAR=F4PRES: 120000:60000 
Option? <RET> 



Referencing task is created using normal procedure to reference 
the library F4PRES. 
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160000 APR 7 
140000 APR6 
120000 APR 5 
100000 APR 4 
60000 APR 3 
40000 APR 2 

20000 APR1 
APRO 



VIRTUAL 
MEMORY 



F4PRES 
(FCSRES) 

12K WORDS 




USER 

(12K WORDS) 



PHYSICAL 
MEMORY 



F4PRES 
(FCSRES) 



USER 



Figure P-3 Referencing Combined Libraries 
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Example task-build commands for building one library, then 
building the second (referencing) library (Figure F-4) : 

>LINK/MAP/NOHEADER/ SHAREABLE : LIB R AR Y/ S YMB L__T AB L E - 

->/OPTIONS/CODE:PIC FCSRES 

Option? STACK=0 

Option? PAR=FCSRES: 0:20000 

Option? <RET> 

>LINK/MAP/NOHEADER/ SHAREABLE : LIBRARY/SYMBOLJTABLE- 

->/OPTIONS F4PRES , LB : [1,1] F4P0TS/LIBRARY 

Option? STACK=0 

Option? LIBR=FCSRES:RO 

Option? PAR=F4PRES: 140000:40000 

Option? <RET> 



Referencing task is created using normal procedure to reference 
just the library F4PRES. F4PRES must be mapped using APRs 6 and 7 
because it is built absolute. FCSRES is mapped at the next 
available APR, namely APR 5, because it is built position 
independent . 
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PHYSICAL 
MEMORY 



160000 APR 7 
140000 APR 6 
120000 APR 5 
100000 

60000 

40000 

20000 

APR 



VIRTUAL 
MEMORY 




F4PRES 



FCSRES 



USER 



Figure F-4 Building One Library, Then Building 
a Referencing Library 
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FCS1 



FCS2 



F4PCLS 




CALL .OPEN' 



OPEN:: 
D I SPAT 



USER 



.FSRPT: 



JMPTBL: 



.OPEN' 

.PUT 

.GET 



AUTOLOAD ROUTINE, MAPS TO 
FCS1, THEN TRANSFERS CONTROL 



Figure F-5 Revectoring 



See Section 5.2.1.3 (on User Task Vectors Indirectly Resolve all 
Interlibrary References) in the RSX-11M/M-PLUS Task Builder Manual 
for additional information on revectoring. See also Section 5.2.3 
on Examples for commented task-build commands for building 
libraries with revectoring. 
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Example task-build commands when revectoring is used 
(Figure F-6) : 

>LINK/MAP/NGHEADER/SHAREABLE : LIBRARY/SYMBOL_TABLE- 

->/OPTIONS/CODE : PIC FCSRES/OVERLAY_DESCRIPTION 

Option? STACK=0 

Option? PAR=FCSRES:0:20000 

Option? GBLREF=. CLOSE 

Option? GBLREF=.CSI1 

Option? GBLREF=.CSI2 



Option? GBLREF= . WAIT 
Option? <RET> 

>LINK/MAP/NOHEADER/SHAREABLE : LIBRARY/SYMBOL__TABLE : ■ 
->F4PCLS/TASK : F4PCLS/0PTI0NS F4PRES , LB : [ 1 , 1 ] F4P0TS- 
->/LIBRARY , LB : [ 1 , 1] SYSLIB/INCLUDE : FCSVEC 
Option? STACK=0 

Option? PAR=F4PCLS: 140000:40000 
Option? GBLINC=.FCSJT 
Option? GBLXCL=. CLOSE 
Option? GBLXCL=.CSI1 
Option? GBLXCL=.CSI2 



Option? GBLXCL=.WAIT 
Option? <RET> 



Referencing task is created using normal procedure to reference 
libraries FCSRES and F4PCLS . 
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PHYSICAL 
MEMORY 



VIRTUAL 
MEMORY 



160000 APR 7 
140000 APR6 
120000 APR 5 
100000 APR4 
60000 APR3 



40000 APR 2 _ 



20000 APR1 



APRO 




INITIAL 
L0A D AMD MAP 



F4PCLS 



FCS2 



FCS1 



USER 



ure F-6 Using Revectoring When Referenced Library Has Overlays 
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CLUSTER LIBRARIES 

• Allow shared libraries to overlay each other (Figure F-7) . 

Can use one window for several libraries. 

Only enough virtual address space is needed for 
largest library. 

• One library can call another. 

- Generally moving in one direction only. 

First library in cluster is initially mapped (no 
autoload) . 

When a call is made to another library in cluster: 

Autoload routines save mapping context and map 
called library for a call. 

Original library is remapped for return from 
subroutine. 

• Revectoring is necessary for interlibrary calls (Figure 
F-5). 

Special coding must be included in the resident 
libraries . 

• Some special rules must be followed when building the 
resident libraries. 

• Are useful for FORTRAN tasks using the resident object 
time system (FORRES, F4PRES , or F77RES) , plus layered 
products. 

See Section 5.2 on Cluster Libraries in the RSX-11M/M-PLUS 
Task Builder Manual for additional information. 

Example of task-build command: 

>LINK/MAP/OPTIONS/CODE:FPP CLSDEM , LB : [1,1] HLLFOR, - 
->LB: [1,1] F4P0TS/LB,LB: [1,1] FDVLIB/LB 
Option? CLSTR-F4PCLS , FMSCLS , FCSRES : RO 
Option? <RET> 
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Figure F-7 Cluster Libraries (Sheet 1 of 2) 
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APPENDIX G 
ADDITIONAL EXAMPLE 



The following example READF.FTN, should be available on-line, 
probably under UFD [202,1]. It is needed for the Tests/Exercises. 
Therefore, it is listed here in case it is not available on-line 
at your site. 



PROGRAM READF 



C File READF.FTN 



This task sets event flag 1 and then reads 
flags 1 to 16 and displays them* The display is 
a series of 16 dibits? corresponding to flag 
16 on the left through flag .1 on the right* 
A 1 indicates that the flag is set? 3 
indicates that the flag is clear* 

INTEGER*2 IEv"F<16) >IDSW 
Set event flag 1* 

CALL SETEF (Ij-IDSW) 
Et ranch on directive error 

IF (IDSW ♦ LT ♦ 0) GOTO 1000 
Re3d the event flags into the array ievf. Note 
that in FORT AN ? we can only read 1 flag at a time 
DO 20 1=1 > 16 
CALL READEF (I* IDSW ) 
Branch on directive error 

IF ( IDSW ♦ LT ♦ 0) GOTO 1100 
Check IDSW valuer 2 means set* means clear 
Set the ievf value accordingly (1 means set? 
means 



2) GOTO 10 



10 
20 

C Write 

30 

40 

C Come 

1000 

1010 

1100 
1110 



clear ) 

IF <IDSW .EG. 
IEvT<I)=IDSW 
GOTO 20 
IEvF(I)*l 
CONTINUE 

out flag settings y 
WRITE (5*30) 
FORMAT (' EVENT FLAGS 
WRITE (59 40) <IEvT<J)j> 
FORMAT (' 'yl6I2) 
Oj~tL.Lt. EXIT* 
here on directive errors 
WRITE < 5>1010> IDSW 
FORMAT (' ERROR SETTING 

WRITE < 5*1110) IDSW 
FORMAT <' ERROR READING 
CALL EXIT 
END 



starting with flag 16* 



16* TO 1 
J=16 r 1 y • 



are: 
i) 



FLAG* ERROR CODE = '>I5) 



FLAG. ERROR CODE = '»I5) 



Example G-l Reading the Event Flags (For Exercise 1-1) 
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APPENDIX H 

LEARNING ACTIVITY ANSWER SHEET 



Learning Activity 2-1 (Directives) 

1. Either: a) Do some work, then check the flag by using the 
CALL CLREF (35,IDSW) directive. Check the DSW. IS. SET 
(=+2) means the flag was set; IS.CLR (=0) means the flag 
was clear, or b) read flags 4 through 64 using RDAF$ and 
then test bit 2 of the third word in the buffer to read 
flag 35. In either case, keep doing more specific work 
and periodically check the flag. 

2. The Executive would only set event flag 1 for Task A. It 
would not set Task B's event flag 1; therefore, Task B 
wouldn't realize that the data had been sent. 

3. Local flags are accessible only to the task itself. They 
are specifically provided for synchronization between the 
Executive and a task. 



Learning Activity 6-1 (Overlays) 

(Using Example 6-5) 
1. 

.ROOT-LIB-*' (P-LIB,Q-LIB) 
LIB: . FACTR LB :[ 1 , 1 ] FOROTS/LB 
. END 



2. 

LINK/MAP ROOT,P,Q,LB: [ 1 , 1 ] FOROTS/LB 
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Learning Activity 6-2 



(Using Example 6-6) 
1. Overlay tree. 

JOB1 JOBXX 



2. 



3. 



A B 
I I 



TOTAL 
I 

MAIN 



.ROOT MAIN-TOTAL-LIB-* (A-LIB- (JOB1-LIB, JOBXX-LIB) ,B-LIB) 
LIB: . FACTR LB : [ 1 , 1] FOROTS/LIB 
.END 



.ROOT MAIN-TOTAL-LIB-*! (A-LIB-! (JOB1-LIB , JOBXX-LIB ,B-LIB) 
LIB: .FACTR LB :[ 1 , 1 ] FOROTS/LIB 
.END 

4. 

.ROOT MAIN-TOTAL-LIB-* (A-LIB- (JOB1-LIB, JOBXX-LIB) ,B-LIB) 
LIB: .FACTR LB : [ 1 , 1 ] FOROTS/LB 
.END 
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INTRODUCTION 



This book contains tests/exercises for two different courses, 
Programming RSX-11M in MACRO and Programming RSX-11M in FORTRAN . 
Most of the questions apply to both courses. If a question begins 
with "In MACRO" or "In FORTRAN", that question applies only to the 
specified course. Solutions are provided for all tests/exercises. 
Where it is appropriate, separate solutions are provided for MACRO 
and FORTRAN. Solutions which involve programs should also be 
available on-line. 

Check the Student Guide in the Student Workbook for your 
course for information on how to use the tests/exercises. 



Using System Services 



TEST/EXERCISE 



1. Match the function with the type of system service used to 
perform it. 



Function 

a. The tasks send data 
back and forth to 
each other 

b. The tasks read data 
from a file on disk 

c. The tasks get input 
from an operator 

at a terminal 



Type of System Service 

1. System and task information 

2. Task control 

3. Task communication/coordin- 
ation 

4. I/O to peripheral devices 

5. File and record access 

6. Memory use 



2. Draw a figure to illustrate a method of providing a system 
service through the Executive. 
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Using System Services 



SOLUTION 



1. Match the function with the type of system service used to 
perform it. 



Function 

a. The tasks send data 
back and forth to 
each other 

b. The tasks read data 
from a file on disk 

c. The tasks get input 
from an operator 

at a terminal 



Type of System Service 

1. System and task information 

2. Task control 

3. Task communication/coordin- 
ation 

4. I/O to peripheral devices 

5. File and record access 

6. Memory use 



2. Draw a figure to illustrate a method of providing a system 
service through the Executive. 



See Figure 1-1 or 1-2 
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Directives 



TEST/EXERCISE 



1. In MACRO-11 

a. Modify the task READF to use the $C form of the Read Event 
Flags directive. 

b. Modify the task READF to use the $S form of the Read Event 
Flags directive. 



2. In FORTRAN, modify the task READF to set all of the odd 
numbered flags from 1 to 15(10). 

3. Modify WFLAG and SFLAG to use a global event flag instead of a 
group global event flag. Omit any unnecessary code in the 
tasks. Check with your instructor to find out which event 
flag to use. 

4. Write a task which does some work and periodically checks a 
group global event flag. Have it display a message and exit 
when the flag has been set. Write another task, or modify 
SFLAG to set the flag. 

5. Add a requested exit AST routine to WFLAG. 

6. In MACRO-11, add an odd address trap SST routine to the task 
SST. Include an instruction which causes the trap to occur. 
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Directives 



SOLUTION 



l.a 1 ♦ TITLE READF 

2 ♦ I DENT /()!/ 

♦ ENABL LC 

? + 

* File LEX21A*MAC 



3 
4 
5 
6 
7 
8 
9 
10 

11 
12 
13 
14 

15 
16 

17 
18 
19 

20 
21 
'?? 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 

35 
36 
37 

38 
39 
40 

41 
42 
43 
44 
45 
46 
47 

48 
49 

50 



? Enable lower esse 



f Modified to use the *C form of the Read All Event yyEX 

y Flags directive 

y 

y This task starts upy sets event flag lv reads the 

r event flagsy moves them into registers R0--R3 and then 

y exits* It uses the * form of the directive calls* 

y 

y The flags are returned as follows* 
y 

y word ~" event flags 1-16 

f word 1 - event flags 17-32 

y word 2 - event flags 33-48 

y word 3 ~ event flags 49-64 



MCALL RDAF*C>SETF*>EXIT*S*DIR* ? System n.3cros 

y y EX 



BUFF* 



setf: 



start: 



♦ BLKW 



SETF* 



CLR 

DIR* 

BCS 

RDAF*C 

BCS 
MOV 
MOV 
MOv 
MOV 
1 0T 



R4 

#SETF 

ERR1 

BUFF 

ERR 2 
BUFFyRO 
BUFFf2yRl 
BUFF+4 yR2 
BUFF+6 y R3 



y Come here on directive errors 



ERR2 : 
ERR1 : 



INC 
INC 

MOV 
I0T 

♦ END 



R4 
R4 

*DSUyR0 



START 



y Buffer for event fl3g 

y values 

y DF'B for Set Event Flag 

y directive 

? Clear error counter 

y Set event flag I 

y Branch on dir error 

y Read the event flags? yEX 

y (1 - 64)* 

y Branch on dir error 

y Move the event flag 

y values into the 

y registers 

y Trap and display 

y registers 



y R4=2 for read error 

? R4=l for set event 
y flag error 

f Error code into R0 

y Trap and display the 
y registers 
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2. 



6 
7 
8 
9 
10 

:l.:L 
12 
13 
14 
15 
16 
17 
1 8 
19 
20 

21 
'."> 

23 
24 



z/ 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 



READF.FTN 

File I...EX22 ♦ FTN 

Modified for exercises* Set odd numbered flags* HEX 

This task sets event flag 1 and then reads 
flags 1 to 16 and displays them 



INTEGER*2 IEW < 16 ) , IDSW 
Set odd event f lads* 

DO 5 K=l'»15>2 

CALL SETEF (KxIDSW) 
Branch on directive error 

IF ( IDSW ♦ LT ♦ 0) GOTO 1000 

CONTINUE 

the event flags into the array ievf* 



!EX 
!EX 
•EX 



! !EX 



Read 
that 



Note 



in FORT AN y we 
DO 20 1=1 > 16 
CALL READEF (I > IDSW) 
Branch on directive error 

I F ( IDSW ♦ LT ♦ 0) GOTO 



can only read 1 flag 3t a time 



1100 



C Check IDSW valuev 2 means set? means clear 
C Set the ievf value accordingly (1 means setv 
C means clear) 

IF (IDSW ♦ EG ♦ 2) GOTO .1.0 

IEVF < I ) "-IDSW 

GOTO 20 

10 IEVF<I>=1 
20 CONTINUE 

C Write out flag' settings* starting with flag 16 

WRITE (5>30) 
30 FORMAT (' EVENT FLAGS 16* TO 1* ARE:') 

WRITE (5i»40) (IEvT(J)y J.*16»l»-1> 
40 FORMAT (' ■ / »16I2) 

CALL EXIT 
C Come here on directive errors 

1000 WRITE <5vl010) IDSW 

1010 FORMAT (' ERROR SETTING FLAG* ERROR CODE 

CALL EXIT 
1100 WRITE (5x1110) IDSW 

1110 FORMAT (' ERROR READING FLAG* ERROR CODE 
CALL EXIT 
END 



15) 



15) 
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Directives 



SOLUTION 

1 PROGRAM WFLAG 

2 C 

3 C FILE LEX23A.FTN 

4 C 

5 C Modified to use event flag 35(10) ! ! EX 

6 C 

7 C This task creates the sroup Global event flags? and 

S C then clears event flag 65* and waits for it to be set* 

9 C When the flag is set? it writes a messaae and exits 

10 C 

11 C Install and run instructions* 

12 C 

13 C Run WFLAG y then run SFLAG ♦ At least one of the 
.14 C tasks must be installed? or else the RUN command 

15 C will try to install both tasks under the same 

16 C name (TTnn) 

17 C 

IB WRITE (5?20) 

19 20 FORMAT (' CLEAR AND WAIT FOR EF 35* TO BE SET' > HEX 

20 CALL CLREF (35? IDSW) ! ! EX 

21 IF (IDSW ♦LT* 0) GOTO 1100 

22 CALL WAITFR (35?IDSW) M EX 

23 IF (IDSW J...T* 0) GOTO 1200 
2 4 WRITE (5? 30) 

25 30 FORMAT <' EF 35 4 HAS BEEN SET* FWAIT WILL NOW EXIT') 

26 C HEX 

27 CALL EXIT 

28 C Error processing 

29 C 

30 1100 WRITE (5? 1110) IDSW 

31 1110 FORMAT (' DIRECTIVE ERROR CLEARING EVENT FLAG 35* 

32 1 DSW = ' ? 15) HEX 

33 CALL EXIT 

34 1200 WRITE (5? 1210) IDSW 

35 1210 FORMAT (' DIRECTIVE ERROR WAITING FOR EVENT FLAG 

36 1 35* DSW = ' ,15) 

37 CALL EXIT 

38 END 

1 ♦ TITLE SFLAG 

2 ♦ I DENT /01/ 

3 *ENABL LC ? Enable lower case 

4 9 + 

5 9 FILE LEX23B*MAC 

6 9 

7 9 Modified to use event flag 35* ??EX 

8 ? 

9 9 This task sets event flag 65* It assumes that the 

10 9 group global event flags have already been created* 

1 1 9 

12 9 Assemble and task -build instructions* 

13 9 

14 9 MACRO/LIST LB* CI ? .1. ."JPROGMACS/LIBRARY ? dev * Cuf d3SFLAG 

15 9 LINK/MAP SFLAG? LB * CI ? 1 3PR0GSUBS/LIBRARY 
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Directives 



SOLUTION 



4. 



l 

':> 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

.1.6 

17 

18 

19 

20 

21 
/•, , t 

23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦ TITLE LEX24 

♦ I DENT /01/ 
.ENABL LC 



? Enable lower case 



FILE LEX24.MAC 



This program creates the group- global event flags? 
clears event flag 65*? does some work and periodically 
cehcks event flag 65* When the flag is set it writes a 
message and exits* 

Assemble and task-build instructions* 

MACR0/L I ST/OB JECT ♦* WFLAG LB *■ C .1. ? 1 ZIPROGMACS/LIB-- ? ? EX 
RARY ? dev ♦ Cuf d3LEX24 t- J EX 

LINK/MAP WFLAG? LB* CI ? 1 3PR0GSUBS/LIBRARY 

Install and Run instructions J 

Run WFLAG ? then run SFLAG* At least one of the 
tasks must be installed? or else the RUN command 
will try to install both tasks under the same 
name? TTnn* 

♦ MCALL EXIT*S?WTSE*C?CL.EF$C?CRGF$C ? System 

? macros 
TYPE ? Supplied macro 



START 



♦ MCAI. 
CLR 



~<0 



TYPE 
CRGF*C 

BCC 



? RO used to identify 
? the error 

<LEX24 IS CREATING THE GROUP GLOBAL EVENT FLAGS. - : 
? Create group global 
? event flags 
OK ? Branch on directive ok 

? If group global event flags already exist? 
? Just display message and continue 

CMP *DSW**IE.RSU y Check for efs already 

5 in existence 
ERR1 ? Branch on any other 

? dir error 
<GR0UP GLOBAL EVENT FLAGS ALREADY EXIST.:- 
<CLEAR EF 65. WORK UNTIL IT IS SET> 



OK 



BNE 

TYPE 
TYPE 
CLEF*C 65 



BCS 



ERR2 



? Clear event flag 65 

? Branch on di reactive 

? error 

? Clear counter 



AGAIN* CLR Rl ? Clear counter ??EX 

y Loop 2**16 times? then check flag ??EX 
LOOP* INC Rl ? Increment counter ??EX 

BNE LOOP ? Not yet cycled? 1oop??EX 

? again ? ? EX 
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SOLUTION 



17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 

43 
44 

45 

46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 



.1.0 

c: 



15 
20 



'•>-•> 

A\. X.. 

25 
28 



30 

C En 
C 

C 0h< 
900 
C In 

910 

C Hei 

1000 

1010 



1100 
1110 



1200 
J. 2 1 



WRITE <5»10) 
FORMAT ( ' LEX24 



IS CREATING THE GROUP 



GLOBAL EVENT 
! !EX 



FLAGS' ) 



CALL CRGF (yIDSW) 

IF (IDSW *I...T* 0) GOTO 900 

WRITE <5y20) 

FORMAT (' CLEAR EE 65* WORK UNTIL IT IS SET') 
CALL CLREF < 65 y IDSW) 
IF (IDSW * LT * 0) GOTO 1100 
DO 25 K=l» 65535 
CONTINUE 
WRITE (5v28) 

FORMAT (' COUNTER HAS CYCLED') 
CALL READEF < 65 y I DSW) 



I F < I DSW . I... T ♦ ) G TO 1200 
IF (I DSW *NE* 2) GOTO 22 
WRITE (5*30) 
FORMAT < ' EF 
CALL EXIT 
processing 



!EX 
•EX 
! EX 
! EX 
!EX 
!EX 
!EX 



65* HAS BEEN SET* LEX24 WILL NOW EXIT') 



■ c k f o r c o d e o f •••• 1 7 ? in e a n i n *S f 1 a si s a 1 r e a d y e x i s t 

I F < I DSW . NE ♦ - 1 7 ) GOTO 1000 
that ease* Just d is lay a message and continue* 

WRITE (5*910) 

F R M A T ( ' G R U P G L B A L E V E N T F L AGS A L R EADY E XI ST ' ) 
GOTO 15 

e f o r f a t a I erro r s ? d i s r- 1 a y in e s s a a e a n d e x i t 
WRITE (5 f 1010) I DSW 

FORMAT (' DIRECTIVE ERROR CREATING GROUP GLOBAL 
1EF "S* DSW = ' , 15) 
CALL EXIT 

WRITE (SvlllO) I DSW 

F R M A T ( ' D I R E C T I V E E R R R C L E A R I NO EVEN T F L AG 6 5 * 
1 DSW = ' t 15) 
CALL EXIT 

WRITE <5yl210) I DSW 

F fj R M A T ( ' D I R E C T I V E E R R R R E A D I N G E VENT F L A G 
1 65* DSW = ' y 15) MEX 
CALL EXIT 
END 
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SOLUTION 



51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 



WTSE$C 

BCS 

TYPE 
EXIT*S 
* AST Service 

rexast: type 



65* * Wait for event flag 65 

* to be set 

ERR3 * Branch on directive 

* error 

<EF 65. HAS BEEN SET ♦ WFLAG WILL NOW EXIT.' 



routine 
<WHY ME? 



NOT THIS TIME! ! 2 



ERR3 : 
ERR2 I 
ERR1 ** 
ERRO : 



ASTX*S 
INC 

INC 

INC 

MOV 



IOT 
♦ END 



RO 
RO 
RO 

$DSW*R1 
START 



* *EX 

Type message 

* *EX 

AST exit to return **EX 
RO ~ 3 if error on 
wait for dir 
RO - 2 if error on 

clear flag dir 
RO = 1 if error on 

create group flags dir 
Place DSW in Rl * leave 

R0~0 for specify **EX 

requested exit AST err 
Trap and dump registers 



1 PROGRAM WFLAG 

2 C 

3 C FILE L.EX25 ♦ FTN 

4 C 

5 C Modified to include a Reauested Exit AST ! ! EX 

6 C 

7 C This task creates the group global event flags * and 

8 C then clears event flag 65 ♦ and waits for it to be set* 

9 C When the flag is set? it writes a message and exits 

10 C 

11 C Install and run instruct ions J 



12 C 

13 C Run WFLAG * then run SFLAG* At least one of the 

14 C tasks must be installed* or else the RUN command 

15 C will try to install both tasks under the same 

16 C name (TTnn) 

1 7 C 

18 EXTERNAL REXAST ! ! EX 

19 C Set up Reauested Exit AST ! ! EX 

20 CALL SREA < REXAST * I DSW ) M EX 

21 IF <IDSW .LT* 0) GOTO 950 ! ! EX 

22 WRITE (5yl0) 

23 10 FORMAT (' WFLAG IS CREATING THE GROUP GLOBAL EVENT FLAGS') 

24 CALL CRGF ( * I DSW) 

25 IF (I DSW ♦LT* 0) GOTO 900 

26 15 WRITE (5*20) 

27 20 FORMAT (' CLEAR AND WAIT FOR EF 65* TO BE SET') 

28 CALL CLREF (65* I DSW) 

29 IF (IDSW *LT* 0) GOTO 1100 

30 CALL WAITFR (65* IDSW) 

31 IF (IDSW ♦ LT ♦ 0) GOTO 1200 

32 WRITE (5*30) 
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6. 



3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
.1.7 
18 
19 

20 
21 

23 
24 
25 

26 
27 
28 
29 
30 
31 

32 
33 
34 
35 
36 
37 
38 
39 



♦ TITLE SST 

♦ IDENT /Ol/ 
♦ENABL LC 

y 

? FILE LEX26*MAC 



r Enable lower case 



t Modified to include an odd address trap 



!EX 



y This task sets up an SST vector table to handle SST's 

? for BPTy I0Ty and odd address traps* It then executes 

y instructions to cause these traps to occur* In each 

5 SST routine y a message is displayed and then the task 

y continues* Finally? a TRAP instruction is executed* 

.» Since no user SST routine is specified for TRAF'y the 

? Executive aborts the task* 

5 Assemble and task-build instructions* 

I MACRO/LIST LB* CI ? 1 .1PR0GMACS/LIBRARY y dev J Cuf d3LEX26 

y LINK/MAP LEX26yLBJ CI y 1 3PR0GSUBS/LIBRARY 



♦ MCALL 
♦ MCALL 

Or able: ♦word 



SVTK$CyEXIT*S 
TYPE 



External 
External 



system macros 
supplied macro 



ODDTRP y MPT v" 10 y BPT y I0T 



SST 



start: SVTK*C VTABLEy4 
BPT 

TST 1 



new: 



CLR 



I0T 

EXIT$S 
TRAP 



120000 



vector table 
y y EX 

Have Executive set up 
SST table 
BPT instruction 
Test location ly ??EX 
causing an odd y?EX 

addr trap y ? EX 

Clear location 120000? 
causing a memory 
protect violation 
I0T instruction 
Exit 

TRAP instruction 
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Using the QIO Directive 



TEST/EXERCISE 



1. Modify SYNCHQ or ASYNCQ to write prompting text (e.g., " TYPE 
SOME TEXT: ") before issuing the read. 

2. In MACRO-11, modify NUMER, replacing the error handling code 
with code which writes out an error message plus the 
appropriate status code. Refer to SYNQER for sample error 
messages . 

3. Modify NOECHO to use one QIO directive to both write the 
prompt and read the input. Also, have the read timeout if no 
key is struck for 20(10) seconds, in which case, display a 
timeout message and exit. 

4. Write a task which prints a message on every terminal in the 
system. The task should break through any pending I/O at the 
terminal. (Note: This task must be task-built as a 
privileged task, using the /PRIVILEGED : qualifier in the 
task-build command; /PR:0 in MCR) 
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l. 



6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 

21 
?i 

23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 



♦ TITLE SYNCHQ 

♦ I DENT /Ol/ 
♦ ENABL LC 



y Enable lower case 



FILE LEX31.MAC 



Modified to display prompting text 



EX 



This task reads a line of text from the terminal ? 
converts all upper case characters to lower case? and 
prints the converted message back at the terminal* It 
uses synchronous QIO directives* 



IOSB: 
BUFF : 
PRMPTJ 
LPRMPT 



start; 



loop: 



♦ MCA LI... QI0W*C f QI0W$S y EXIT*S 



y External system 
y macros 



♦ BLKW 

♦ BLKB 
♦ASCII 
=*-PRMPT 

♦ EVEN 



2 y I/O Status Block 

80* t Text buffer 

/TYPE SOME TEXT: / 5 Prompt 

y Length of prompt 



y y EX 
y y EX 
y y EX 



CLR 
CLR 



R5 
R4 



QI0W*C I0*WVBy5yly ylOSB 



BCS 

TSTB 

BLT 

QI0W*C 

BCS 
TSTB 
BLT 
MOV 

CLR 

CMPB 



BLT 

CMPB 

BGT 

y Here if upper 
M0VB 
ADD 
M0VB 



ERR3 
IOSB 
ERR3A 

I0*RVBy5yly 

ERR1 
IOSB 
ERR1A 
I0SB+2yR0 

Rl 

BUFF(Rl) y#"i 
NEXT 

BUFF(Rl) t*' 
NEXT 

casey move 
BUFF(R1 ) yR2 
#32* yR2 
R2yBUFF(Rl ) 



IOSB 



Z 

to 



Error Count 

Error indicator ~ 

means directive error 

(DSW in R3)y neg 

means I/O error 

(I/O status in R3> 
- <PRMPTy LPRMPT y40> 
Display prompt yyEX 
Branch on dir error? r EX 
Check for I/O erroryJEX 
Branch on I/O error? ?EX 
■<BUFFy80*> y Issue 
y read 
Branch on dir error 
Check for I/O error 
Branch on I/O error 
Get count of characters 

typed in 
Offset into buffer to 

character 
Check for upper case 

ASCII character 
Branch if below range 



Branch if above range 
register R2 and convert 
Move to register 
Convert to lower case 
Replace in message 
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1 

X 




2 


r 


-7 
\5 




4 


C 


c i 
\J 


r 


6 


C 


7 


c 


8 


c 


9 


c 


10 


c 


11 


c 


12 


c 


13 




14 




15 




16 




17 




18 




19 




20 




21 


c 


22 




23 


c 


24 




25 




26 




27 


c 


28 




29 




30 




31 




32 




33 


c 


34 




35 




36 


c 


37 




38 


c 


39 




40 


c 


41 




42 


c 


43 




44 




45 


50 


46 


c 


47 




48 


c 


49 




50 


c 


51 





PROGRAM ASYNCQ 



FILE LEX31.FTN 



Modified to display prompting text 



! !EX 



This program reads a line of text from the terminal t 
converts any upper case characters to lower case and 
prints the converted message back at the terminal* 
It uses asynchronous GIOs and an event flag for 
synchronization* 



BYTE I0SB<4) f IBUF(80) 
DIMENSION IPAR(A) fK<10) 
EQUIVALENCE ( NUM r I0SB ( 3 ) ) 
REAL PRMPT(4) 

PRMPT /'TYPE' j 
I0WVB/" 11000/ 
I0RUB/" 10400/ 
IvTC/MO/ 

for the QIO 



0M' f 'E TE ' * 'XT: 



DATA 
DATA 
DATA 
DATA 
Set up values 
I UN IT ^5 

Set up for QIO to issue prompt 

CALL GET ADR ( I PAR ( 1 ) t PRMPT ( 1 ) ) 
IPAR(2)=16 
IPAR(3>="40 
Issue asynchronous write 

CALL Q 1 ( 1 W MB y 1 UN I T y 5 9 , 1 OSB y I P AR y I DS ) 
IF (IDS ♦ LT* 0) GOTO 780 
CALL WAITFR<5>IDS) 
IF (IDS ♦ LT ♦ 0) GOTO 785 
IF (I0SB(1) ♦ L T ♦ 0) GOTO 790 
Set up for read 
IPAR<3)=0 
l'PAR(2)==80 
Get the address of the I/O buffer 

CALL GET ADR ( I PAR ( 1 ) y IBUF ( 1 ) ) 
Issue the QIO 

CALL Q 1 ( I OR VB 1 1 UN I T , 5 v , I OSB 1 1 P AR r I DS ) 
Check the directive status 

IF (IDS »LT ♦ 0) GO TO 800 
Do some work while I/O operation is 
DO 50 1=1 f 10 
K(I)=64*I 
CONTINUE 

Wait for I/O to complete 
CALL WAITFR(5rIDS> 
Check directive status 
IF (IDS »LT* 0) GO TO 805 
Check the I/O status 

IF (IOSB(l) ♦LT* 0) GO TO 810 



! !EX 
' / ! ! EX 



EX 
EX 
EX 
EX 
EX 
EX 
EX 
EX 
EX 
EX 
EX 
EX 



being performed 
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2. 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 



♦ TITLE NUMER 

♦ I DENT /01/ 
♦ ENABL LC 



? Enable lower case 



FILE LEX32*MAC 



Modified to include error message code 



r r EX 



This task does a simple addition and outputs the 
results* It demonstrates the use of $EDMSG for 
formatting messages with numeric data 



r Data 

a: 



♦ MCALL 
♦ MCALL 
♦NLIST 



♦ WORD 

♦ WORD 

♦ BLKW 



GIOW$yEXIT$SyDIR* y System macros 
QI0W*S f System macros y?EX 

BEX r Do not list binary 

r extensions 



10 



r 1st addend and start 
r of argument block 

r 2nd addend 

r Location for sum 



23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



OUT! Q.I0W* I0*WVBy5yly ylOSBy y<BUFy y40> J QIO for 

y output message 
I0SB: .BLKW 2 ? I/O status block 

? 

? Set up for *EDMSG 



but: 
fmes: 



♦ BLKB 
♦ASCIZ 



r Set up for error 

♦ EVEN 
arg: .BLKW 
fmtid: »asciz 

FMTli: *ASCIZ 

♦ EVEN 



80* t Output buffer 

/%l'U WAS ADDED TO %D.y GIVING %D*/ 
y Format string 
messages using $EDMSG y?EX 

f ? EX 

1 r Argument block? rEX 

/DIRECTIVE ERROR ON WRITE » DSW = ZD/ yJEX 
'I/O ERROR ON WRITE r I/O STATUS « %D'??EX 

yyEX 



♦ LIST 

♦ EVEN 
START : MOV 



Set 



BEX 5 List binary extensions 

5 Move to word boundary 

AyC r Move 1st addend to sum 

9 word 

ByC y Add 2nd addend to form 

9 sum 

? Addr of output buffer 

y Addr of format string 

9 Mdr of argument block 

9 Make call y character 

y count returned in Rl 



ADD 



up for call to *EDMSG 
MOV #BUFyR0 
MOV #FMESyRl 
MOV #A y R2 

CALL $EDMSG 
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4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦ TITLE NO-ECHO 

♦ I DENT /Ol/ 

♦ENABL LC * Enable lower case 

FILE LEX33*MAC 

Modified to combine QIOs 3nd include timeout yyEX 

This task writes a prompt and then issues a QIO to read 
from the terminal without echo* It then displays the 
word which was entered* 

Assemble and task-build instructions J 

MACRO/LIST LBiCly 1 .IPROGMACS/LIBRARY y dev : Cuic3LEX33 
LINK/MAP LEX33 y PRQGSUBS/LIBRARY 

♦MCALL EXITSSy QI0W$C y QI0W*S y System macros 
♦MCALL DIRERR y I0ERR y Supplied macros 

r Data 



MES i 
LEN 

buff: 

BLEN 

buf: 

TMOMS ♦ 
LTMOMS 

iosb: 
lent: 



♦NLIST 
♦ASCII 
♦ASCII 



BEX 



y Don't list of binary 
J extensions 



/SECRET WGRDJ / y Prompt messes$e 
♦ -MES i Length of prompt 

<15>/N0 LONGER A SECRET WORD* / 

? Preceding remark 
~ *~BUFF 5 Length of Remark 

♦BLKB 80* y Input buffer 

♦ASCII /READ TIMED OUT/ y Timeout message yyEX 
= ♦ -TMOMS yyEX 
♦EVEN y Word alisn for IOSB 

♦WORD y IOSB is broken into 

♦WORD y two parts for 

< y convenience ♦ 

y Define functions locally to allow us of an assignment 
y statement to shorten directive statement 
10* RPR =004400 y Define functions 

=20 ? 
==200 ? 

=<IO»RPR!TF*RNE!TF*TMQ> y QIO function code 
♦LIST BEX y List binary extensions 



TF ♦ RNE 
TF ♦ TMO 
I0.FNC 



Code 



START! 



QI0W*C I0»FNCy5yly ylOSBy y<BUFy80, y 2 y MES y LEN y 44> 

y Issue read 3fter yyEX 
y p rompt 5 y EX 

BCS DERR1 y Branch on dir error 
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1 






PROGRAM N0ECH0 




2 
3 


C 
C 


File 


LEX33.FTN 




4 


c 








5 
6 


c 
c 


Modified to use read after prompt and to timeout HEX 


7 


c 


This 


task prompts for input » reads it without echo and 


8 


c: 


then 


skips to the next line and display 


s the input 


9 


c 


text 


and exits* 




10 


c 








11 






BYTE BUFF<80> >I0SB<4> rCR(l) 




12 






INTEGER PARM(6) 




13 






REAL PR0MPT(4) » 


Prompt ! ! EX 


14 


c 








15 






DATA I0FNC /"4620/ ! 


QIO ! !EX 


16 


c 




i 


function ! ! EX 


17 


c 




j 


code ! ! EX 


18 






DATA ISTMQ /2/ ! 


Timeout ! ! EX 


19 


c 




I 


status ! .' EX 


20 






DATA CR /"15/ ! 


Carriage return char 


21 






DATA PROMPT / ' SECR ' » " ET W ' ? ' ORD f ' r ' ' / 


22 


c 




! 


Text H EX 


23 


c 


Set up the 1/0 parameter list 




24 






CALL GETADR ( PARM ( 1 ) t BUFF ( 1 ) ) ! 


buffer address 


25 






PARM(2) = 80 ! 


Buffer length 


26 






PARM (3) = 2 ! 


Timeout : = 2 ! ! EX 


27 


c 




i 


* 10 sec ! !EX 


28 






CALL. GETADR ( PARM ( 4 ) , PROMPT ( 1 ) ) .» 


Prompt addr ! ! EX 


29 






PARM(5) = 13 ! 


Prompt length!! EX 


30 






PARM(6) - "44 ! 


Vertical ! ! EX 


31 


c 




i 


format contrMEX 


32 


c 


Issue 


read no echo? read after prompt t 


with timeout !!EX 


33 






CALL WTO 10' ( I0FNCy5y 1 ? r IOSByPARMr 


IDS) 


34 






IF < IDS ♦LTV 0) GO TO 100 ! 


Dir error? 


35 






IF <I0SB<1) A.T* 0) GO TO 110 ! 


I/O error? 


36 


c 


Check 


for timeout 




37 






IF (IOSB(l) ♦ NE ♦ ISTMO) GOTO 1 ! 


Branch if no ! ! EX 


38 


c 




i 


timeout ! ! EX 


39 






TYPE *»'READ TIMED OUT ' ! 


Display ! ! EX 


40 


c 




i 


message ! ! EX 


41 






CALL EXIT ! 


and exit ! ! EX 


42 


1 




WRITE <5,2) CRf (BUFF(I) , I = lyI0SB<3> ) ! Echo input 


43 


2 




FORMAT <' 'yAlr'NO LONGER A SECRET WORD: ' r 80A1 ) 


44 






CALL EXIT 




45 


c 








46 


c 


Error 


conditions 




47 


c 








48 


100 


TYPE *r 'DIRECTIVE ERROR ON READ* 


STATUS ---- ' >IDS 


49 






CALL EXIT 




50 


110 


TYPE *? M/0 ERROR ON READ* CODE 


= 'ylOSB(l) 


51 






CALL EXIT 




52 






END 
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Using the QIO Directive 



SOLUTION 



1 PROGRAM LEX34 

2 Cf 

3 C FILE LEX34 ♦ FTN 

4 C 

5 C Solution to Module 3> Lab Exercise 4 

6 C 

7 C Task does 3 write breakthrough to all terminals* 

8 C 

9 C Task-build with /PRIVILEGED :0 Qualifier 



10 C- 

11 INTEGER TTUNITfDSW 

12 DATA TTUNIT/0/ ! First output to TTO ♦ 

13 INTEGER PARAM ( 6 ) t I0SB < 2 ) 

14 BYTE SUCCOD < 2) ' ! I/O success codes 

15 EQUIVALENCE ( SUCCOD t I0SB ) ! First bytes of I0SB 

16 INTEGER IEIDU ! Mnemonic for "Illegal 

17 DATA IEIDU/- 99/ • Device or Unit" DSW code 

18 INTEGER I0FCOD ! I/O function code ' 

19 C ! mnemonic 

20 DATA I0FC0D/-501/ ! Write logical block r 

21 C ! write breakthrough » 

22 C ! and restore cursor 

23 C 

24 C Load parameter list 

25 CALL GET ADR < PARAM < 1 ) t ' HELLO THERE ' ) 

26 PARAM < 2 ) = 11 ! Length of string 

27 PARAMO) = "40 ! Blank for carr* Ctrl* 

28 10 CALL ASNLUN<4» 'TT' > TTUNIT r DSW > ! Assign LUN 4 to 

29 C ! TTn \ 

30 IF (DSW*LT*0) GOTO 900 

31 CALL WTGI0(IQFC0D»4*1» »I0SB> PARAM r DSW) 

32 IF <DSW*LT*0) GOTO 910 ! Directive error 

33 IF (SUCCOD(l) *NE*1) GOTO 920 ! I/O error 

34 TTUNIT = TTUNITf 1 

35 GOTO 10 

36 C 

37 C Error from ASNLUN* If ASNLUN failed because of illegal 

38 C unit number* must have passed the last terminal* Exit* 

39 900 IF (DSW* EG* IEIDU) CALL EXIT 

40 TYPE 905 * DSW ! Other error 

41 905 FORMAT (' ERROR ON ASNLUN* DSW = 'yI6) 

42 CALL EXIT 

43 910 TYPE 915yTTUNIT>DSW 

44 915 FORMAT (' DIRECTIVE ERROR ON QIO TO TT'r02>':'/ 

45 1 ' DSW * ' yI6) 

46 CALL EXIT 

47 920 TYPE 925 y TTUNIT » SUCCOD (2) r SUCCOD ( 1 ) y I0SB (2) 

48 925 FORMAT (' I/O ERROR ON QIO TO TT'y02y'*'/ 

49 1 ' I/O STATUS BLOCK = 'yI4»' »M4»' /'»I6) 

50 CALL EXIT 

51 END 
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TEST/EXERCISE 



Modify RECV1 and SEND1 to synchronize using Suspend and Resume 
directives instead of event flags. 

Modify RECV2 so that the display includes the name of the 
sending task in addition to the data. 

Write another sender task to send data to RECV2. Modify the 
receiver so that it receives data from your task only, not 
from SEND2. 

Modify SPAWN so that it spawns CLI..., MCR..., or ...DCL 

several different times and sends a different MCR or DCL 
command line each time. Display the exit status after each 
command executes. 

Write a parent task and an offspring task. Have the parent 
spawn the offspring. Have the offspring emit status to the 
parent every five seconds for 30 seconds and then exit. Have 
the parent display each status value. Optional: Use an AST 
routine in the parent for synchronization. 
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l. 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
.1.4 
15 
16 
17 
18 
19 

20 

21 
'?':> 

23 
24 
25 
26 
27 
28 
29 
30 
3.1 
32 
33 
34 
35 
36 
37 

38 
39 
40 
41 
42 
43 
44 



♦TITLE SEND! 
♦I DENT /01/ 
♦ENABL LC 

FILE LEX41A*MAC 



r Enable lower case 



Modified to use Suspend and Resume directives foryfEX 
synchronization r?EX 

This task prompts at TI* for a line of text and sends 
the data to RECV1 for processing* Synchronization is 
handled through a common event flag* 

Assemble and task-build instructions* 

.'.'••MACRO/LIST/OBJECT ♦* SEND1 LB* CI y 1 3PRQGMACS/LI - y y EX 
->BRARY y dev ♦ Cuf d3LEX41 A 

> LINK /MAP SEND1 y LB ♦ C 1 y 1 3PR0GSUBS/LIBRARY 

Install and run instruct ions J RECVl must be installed 
and run prior to running SENB1 ♦ RECV1 continues to run 
until it receives 3 data packets* 

♦ MCALL SDAT*CyEXIT$SyRSUM*C ? System macros* iEX 
♦ MCALL TYPE y INPUT r DIRERR 5 Supplied macros 



buffer: *blkb 

y 

♦ ENABL 

f 

START ♦ * TYPE 

INPUT 

SDAT*C 

BCC 

DIRERR 



26* 
LSB 



r Data buffer to be sent 

i Enable local symbol 
y blocks 



i$: 



RSUM$C 
BCC 

DIRERR 
EXIT$S 
♦ END 



<TYPE A LINE OF TEXT* 26 CHARACTERS OR LESS> 
? Type prompt 

♦BUFFER y #26* y Get text to send 

RECV1 v BUFFER y Send data to RECV1 y?EX 

1* ? Branch on direct vie ok 

<UNABLE TO QUEUE DATA TO RECV1> r Display 

y error message and exit 
RECV1 ? Resume RECV1 yyEX 

5$ y Branch on directive okyyEX 

<UNABLE TO RESUME RECV1> ? yyEX 
y Exit y yEX 

START 
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6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



y + 



♦ TITLE RECV1 

♦ I DENT /01/ 

♦ENABL L.C 5 Enable lower case 

FILE LEX41EUMAC 

Modified to use Suspend and Resume for synchronization y y EX 

This task and receives data from any sender task 
(e*g*y SENDl)*l't prints the data on Tit* Then it 
waits for another data packet* It does this until it 
has received 3 messages and then exits* 

This task synchronizes with its sender through an 
event flag* 

Assemble and task-build instructions* 

>MACR0/L I ST/OBJECT « RECV 1 LB : L" 1 1 1 1 PR0GMACS/L IB- ? ? EX 
->RARY»dev:Cufd3RECVl 9 5 EX 

LINK/MAP RECV1 y LB J L" 1 y 1 3PR0GSUBS/LIBRARY 

Install and run instructions* RECV1 must be installed 
and run before running SEND1 ♦ 



♦ MCALL 
♦ MCALL 



rbuff: *blkw 



RCVD$CyEXIT*SySPND$Sy System macros y JEX 
TYPE* DIRERR > Supplied macros 



♦ENABL LSB 



y Receive buffer 

f Enable local symbol 
i blocks 



start: 
again: 



MOV 

SPND*S 

BCC 

DIRERR 



#3 1 R5 



3$ 



f Initialize message 
r counter 

} Suspend self until* y EX 
y message arrives 
? Branch on directive ok 
<SUSPEND DIRECTIVE FAILED.':- y Display yyEX 
y error message and exit 
y We get here when resumed by SEND1 yyEX 
3*: RCVD$C y RBUFF y Receive from anyone 

BCC 5$ ? Branch on directive ok 

DIRERR <RECEIVE DIRECTIVE FAILED IN "RECV1"> 

? Display error message 
y and exit 

y Successful receipt 

5*: TYPE <DATA RECEIVED BY " RECV1 " : > y Display 

y data 
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4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
IS 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦TITLE RECV2 
♦ IDENT /01/ 
♦ENABL LC 

i 

y FILE LEX42*MAC 



r Enable lower case 
y y EX 



Modified to display the sender task name in addition yyEX 
to the d3ta y y EX 

This task receives data from another task* It prints 
the data* along with a headery on TI** Then it waits 
for another data P3ckety continuing this until it has 
received 3 messages* 

This task synchronizes with its sender using RCST$* 
Because of this synchronization y the tasks can he run 
in any order? with any relative priorities* 



y Assemble and task build instructions* 
? 

y >MACR0/L1ST/0BJECT:RECV2 LB:Clyl3PR0GMACS/LIB~y ?EX 

y ~>RARY t dev ♦ Cuf d3LEX42A yyEX 

y >L INK/MAP RECV2 y LB ♦ C 1 y 1 3PR0GSUBS/LIBRARY 

y 

5 Install and run instructions* RECV2 must be installed* 
y 

♦MCALL RCST$CyRCMD*CyEXIT$S f System macros 



♦ MCALL TYPE y D.I RERR 



rbuff ♦ ♦ blkw 15* 

tasknm: *blkw 3 

y 

* ENABL LSB 



y Supplied macros 

y Receive buffer 

y Buffer for task name r? EX 

y Enable local symbol 
y blocks 



START i MOV 
RECEIV: RCST*C 
BCC 

D I RERR 



#3 y R5 

y RBUFF 
5* 



y Set up message counter 
y Receive from anyone 
y Branch on directive ok 
<RECEIv"E DIRECTIVE FAILED IN "RECV2"> 

y Display error message 
y and exit 

y Successful receipt or unstopped by another task* First 
y check for unstopped after being stopped y in which case 
y we have to receive the data 

5* ♦ CMP $DSWy#IS*SET y Were we stopped due to 

y no data 

5 If not, we have a data 
y packet 

y Now get the packet 
y Branch on directive ok 



BNE 



6$ 



RCUD4C y RBUFF 
BCC 6$ 
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20 
21 
22 
23 
24 
25 
26 
27 
28 
2? 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 

50 
51 
52 
53 
54 
55 
56 
57 
58 



INTEGER 
INTEGER 
INTEGER 



RBUFF ( 15 ) 
DSW*ISSET 
TASKNMC3) 



DATA ISSET/2/ 



! Receive buffer 

! Buffer for ASCII form!! EX 
! of task nam© ! ! EX 

! DSW code mnemonic 



10 



DO 100r I=i>3 
CALL. RCST ( t RBUFF > DSW ) 
IF <DSW*GE*0) GOTO 50 
Type *> 'RECEIVE DIRECTIVE 
1 DSW = ' t DSW ! 
GOTO 1000 ! 

Successful receipt or unstopped 
check for unstopped after being 
we have to receive the data 

IF (DSW*NE*1SSET> GOTO 60 



! Receive from anyone 



FAILED IN "RECV2" ♦ 
Display error message 

and exit- 
by another task* First 
stopped v in which case 

Were we stopped due 
to no data? If not 
( NE ) i we have a 
data packet 



Stopped due to no data* 

CALL RECE I V < » RBUFF y > DSW ) 
IF (DSW*EQ*1) GOTO 60 
TYPE *r 'RECEIVE DIRECTIVE 
1UNST0PPED* DSW = '>DSW 
GOTO 1000 
Display data 

CALL R50ASC ( 6 r RBUFF y TASKNM ) 

TYPE 75 y TASKNM y ( RBUFF ( J) j J=3y 15) 
FORMAT (' DATA RECEIVED BY " RECV2 " 
lA2ylXy 13A2) 
CONTINUE 
received 3 messages 
TYPE *y ' "RECV2" HA 
1 NOW EXIT' 
CALL EXIT 
END 



60 



100 

C Have 



1000 



! Now get the packet 

AILED AFTER "RECV2" 
Display error 
message a n d e x i t 



! !EX 

! ! EX 
/IX t 3 » !EX 
! !EX 



RECEIVED 3 MESSAGES AND WILL 



! Exit 
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1 




n 


C 


3 


C 


4 


C 


5 


C 


6 


C 


7 


C 


8 


C 


9 


C 


10 


c 


11 


c 


12 


c 


13 


c 


14 


c 


15 


c 


16 




17 




18 




19 




20 




21 




'yy 


c 


23 




24 




25 


5 


26 




27 
28 




29 




30 


10 


31 




32 




33 


c 


34 


c 


35 


c 


36 




37 


c, 


38 


c 


39 




40 




41 


20 


42 





PROGRAM LEX43A 



FILE LEX43A*FTN 



! !EX 



A second sender task to send data to RECV2 



! ! EX 



This task prompts at Tli for a line of text and sends 
the data to RECV2 for processing* The receiver will 
continue to run until it receives 3 messages* 
Synchronization is handled through RECv"2's stop bit* 
RECV2 and LEX43A may be run in any order* 



Install and run instructions J LEX43B must be 
installed under the name RECv"2* 



! !EX 
! !EX 



BYTE BUFFER (26) 

INTEGER DSW 

REAL RECV2 

DATA RECV2/5RRECV2/ 

INTEGER IEITS y 1EACT 

DATA IEITS y IEACT/--8 y 



! Send buffer 



! Receiving task name 
! Error mnemonics 



-7/ 



TYPE *y ' TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS' 
READ <5y5) BUFFER 
FORMAT <26A1) 

CALL SEND < RECV2 y BUFFER r y DSW ) ! Send data to RECM2 
IF (DSW*EQ*1) GOTO 10 

DATA TO "RECV2 u ♦ DSW « ' 



'UNABLE TO QUEUE 



TYPE * 
1 y DSW 

CALL USTP(RECV2yDSW) ! 
IF <DSW*EQ*1) GOTO ,20 ! 
IF (DSW*EQ*IEITS) GOTO 20 



IF (DSW*EO*IEACT) GOTO 20 

i 
! 

TYPE *y 'UNABLE TO UNSTOP 

I 

CALL EXIT ! 
END 



Unstop RECV2 

Branch on directive ok 

! I s n ' t h e s t o p p e d ? 

That ' s ok y he'll p i ck 

up data when he 

executes RCDS* 
! Is he not active? If 

noty he'll pick up 

data when activated 
■RECV2" ♦ DSW = ' yDSW 
Any other error is bad 
Exit 
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47 r Successful receipt or unstopped by another task* First 

48 f check for unstopped after being stopped * in which case 

49 f we have to receive the data 

50 5$: CMP *DSWy#IS*SET 5 Were we stopped due to 

51 ? no data 

52 EfNE 6$ f If notr we have a dat3 

53 i packet 

54 RCVD*C LEX43Ay RBUFF ? Now get the packet 

55 BCC 6$ ? Branch on directive ok 

56 DIRERR <RECEIVE DIR FAILED AFTER "RECV2" UNST0PPED> 

57 r Display error message 

58 ? and exit 

59 6*: TYPE <DATA RECEIVED BY "RECV2":> } Display 

60 r text and 

61 TYPE #RBUFF+4r#26* > data sent 

62 ? SOB RS^RECEIV ? Decrement message 

63 ? counter* Receive 3g3in 

64 i if haven't received 3 

65 i yet 

66 DEC R5 f i EX 

67 BE « DONE HEX 

68 JMP RECEIV HEX 

69 DONE: TYPE <"RECV2" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT> 

70 i Type exit 

71 i message 

72 EXIT*S 9 Exit 

73 ♦ END START 



1 PROGRAM RECV2 

2 C 

3 C FILE LEX43B*FTN MEX 

4 C • ■ 



5 C Modified to receive only from LEX43A MEX 

6 C NOTE! TASK WILL EXIT WITH A NO DATA QUEUED ERROR IFMEX 

7 C SEND2 SENDS DATA* MORE COMPLICATED CODE IS NEEDED MEX 

8 C TO CHECK FOR SEND2 SENDING DATA AND UNSTOPPING RECV2 M EX 

9 C 

10 C This task receives data from another task (e*g* SEND2)* 

11 C It prints the data^ along with a header t on TIJ* Then 

12 C it waits for another data packet? continuing this 

13 C until it has received 3 messages* 

14 C 

15 C This task synchronises with its sender using RCST* 

16 C Because of this synchronization)' the tasks can be run 

17 C in any order* with any relative priorities* 

18 C 

19 C Install and run instructions: LEX43B must be MEX 

20 C installed under the name RECV2* MEX 

21 C 
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6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 



♦TITLE SPAWN 
♦ I DENT /02/ 

♦ENABL LC 



f Enable lower case 



File LEX44 * MAC 



EX 



This program spawns MCR***? passes it a series of ??EX 
command lines* waits for each to exit* and yyEX 
displays each command's exit status* yyEX 

Assemble and task-build instructions* 

MACRO/LIST LB* CI y 1 UPROGMACS/LIBRARY y dev : Cufd3LEX44 
LINK/MAP LEX44 y LB : C 1 y 1 3PR0GSUBS/LIBRARY 

♦ MCALL SPWN*yEXIT$SyWTSE*CyaiOW*SyQIOW*C 

i System macros 



cmdi: 

LEN1 
CMD2 i 
LEN2 •• 
CMD3 ♦ 
L.EN3 : 

smes: 

LSMES 

iosb: 



y Supplied macros 

? Inhibit listing of 

f binary extensions 

i Command line 

y Lendth of command 



♦ MCALL DIRERR y I0ERR 
♦NLIST BEX 



♦ASCII "PIP **MAC/LI 

=*~CMD1 

♦ASCII /ACT/ 
♦ -CMC 2 

♦ASCII /TIM/ 
♦ -CMD3 



♦ ASCII /SPAWN IS STARTING AND WILL SPAWN/ 
♦ASCII / MCR COMMANDS/ y Startup message 



?EX 
?EX 
J EX 
?EX 
y EX 
yEX 

J EX 
y EX 



■=.-SMES 

♦ EVEN 

♦ BLKW 



exstat: ♦BLKW 
cmdtbl: .word 

♦ WORD 

♦ WORD 

♦ WORD 

spawn: spwn* 



2 
8, 

CMDI y LEN1 
CMD2* LEN2 
CMD3rLEN3 




y Length of message 

y I/O status block 

y Exit status block 

y Table indexing 

y MCR commands 



y End of table 
MCR ♦♦♦yyyyy.lyy EXSTAT 



t yEX 
f $ EX 
y y EX 
y y EX 



y EX 



80 ♦ 



y Output message buffer 



BUFF ♦ ♦BLKB 
y Format string? 

FMT: ♦ ASCI I /%NSPAWN REPORTING: COMMAND/ 

♦ASCIZ / COMPLETED ♦ EXIT STATUS WAS %D.%N/ 
♦ EVEN 

START: QIOWSC I0*WVBy5yly ylOSBy y <SMESy LSMES y40> 

BCS ERR ID ? Branch on dir error 

TSTB IOSB y Check for I/O error 

BLT ERR1I y Branch on I/O error 



f yEX 
y y EX 
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1 PROGRAM SPWN 

2 C 

3 C File LEX44.FTN 

4 C 

5 C This program spawns ...DCLy passes it s series of ! !EX 

6 C command lines* waits for each to exit* and HEX 

7 C displays each command's exit status* ! ! EX 

8 C 

9 C Data 

10 INTEGER EXSTAT<8) rPLIST(6) t DSW 

11 BYTE BUFF (80) 

12 C Commands to be spawned* ! ! EX 

13 C 

14 C DIR *.MAC ! ! EX 

15 C SHOW TASKS/ACTIVE ! ! EX 

16 C SHOW TIME ! ! EX 

17 C 

18 REAL CMD(5>3> ! ! EX 

19 DATA CMD/'DIR ','*. MA' r'C , r t 

20 1 'SHOW',' TAS' r 'KS/A' r 'CTIV t 'E' r 

21 2 'SHOW'*' TIM ' r ' E ' > t 0/ HEX 

22 INTEGER LEN( 3) 

23 DATA LEN/9,17»9/ 

24 C 

25 REAL DCL 

26 DATA DCL/6R. . .DCL/ 

27 C 

28 C Code 

29 WRITE (5*15) 'Write message 

30 15 FORMAT (' SPAWN IS STARTING AND WILL SPAWN 

31 1 'DCL COMMANDS') M EX 

32 DO 30rl=l»3 

33 CALL SPAWN (DCL * r rlr rEXSTAT y t CMD( r LEN( I ) 

34 If, rDSW) MEX 

35 ! Spawn DCL 

36 IF (DSW. LT.O) GOTO 900 

37 CALL WAITFR(lrDSW) 

38 IF (DSW. LT.O) GOTO 910 

39 WRITE (5>25) EXSTAT ( 1 ) ♦ AND ♦ • 377 ! Display low 

40 ! b«te of exit status 

41 25 FORMAT (' SPAWN REPORTING: COMMAND COMPLETED. 'r 

42 1 ' EXIT STATUS WAS ' r II f ' . ' ) 

43 30 CONTINUE 

44 CALL EXIT ! Exit 

45 C Error handling code 

46 900 TYPE #> 'ERROR SPAWNING DCL. DSW * ',DSW 

47 GOTO 1000 

48 910 TYPE *f 'ERROR WAITING FOR EVENT FLAG. DSW '« '>DSW 

49 1000 CALL EXIT 

50 END 



Branch on dir error 
Wait for task to exit 
Branch on dir error 
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DIR* 


R4 


f QIOW* to ti: 


52 




BCS 


ERR4 




53 




TST 


R5 


9 Did offspring exit? 


54 




BGE 


3* 


* Yes 


55 




DIR* 


♦CLEF 


9 No* Clear EF 1 again 


56 




BCS 


ERRS 




57 




BR 


1* 


9 Wait 


58 
59 


3$: 


EXIT*S 




9 Once offspring exits* 
* so should parent 


AO 


* 








61 


erri : 


DIRERR 


< ERROR 


ON INITIAL CLEF*> 


62 


ERR 2 * 


DIRERR 


<ERR0R 


SPAWNING LEX45B> 


63 


ERR3 : 


DIRERR 


<ERR0R 


ON WTSE*C> 


64 


ERR4 J 


DIRERR 


<ERROR 


ON QI0W*> 


65 


errs: 


DIRERR 


< ERROR 


ON CLEF$> 


66 


* 








67 


* AST routine* 


entered 


when offspring emits status 


68 


* (negative status value) or exits (positive status 


69 


* value) 






70 


* 








71 


astrtn: 


SETF*C 


1 


* Awaken main code 


72 




BCS 


ERR6 




73 




CMP 


*DSW*#IS*SET * If set* main code is 


74 








* not ready yet 


75 




BEQ 


OVRRUN 


* We've been overrun 


76 




TST 


STATUS 


* Has offspring exited? 


77 




BGE 


4* 


* If so* don't try to 


78 








> reconnect 


79 




CNCT*C 


LEX45B* 


* ASTRTN* STATUS 


80 




BCS 


ERR7 




81 


4*J 


TST 


(SP) + 


* Clean up stack from AST 


82 




ASTX$S 




* Let main code run 


83 


* 








84 


* If a 


new status comes 


in before we're done with the old 


85 


* one* 


something is wrong* Stop everything* 


86 


* 








87 


ovrnms: 


♦ASCII 


/STATUS 


; RECEIVED BEFORE READY ♦ / 


88 




♦ASCII 


/ ABORTING BOTH TASKS*/ 


89 


0VRNML 


= ♦ -OVRNMS 




90 




♦ EVEN 






91 


* 








92 


ovrrun : 


QI0W*C 


10 * WVB * 5 * 3 9 * * * <0v"RNMS * OVRNML * 40> 


93 




ABRT*C 


I...EX45B 


* Abort offspring 


94 




BCS 


ERRS 




95 




EXIT$S 




* Exit this task 


96 


* 








97 


ERR 6 1 


DIRERR 


< ERROR 


FROM SETF* IN AST ROUTINES- 


98 


ERR 7 ♦ 


DIRERR 


<ERROR 


CONNECTING TO OFF SPRING > 


99 


ERRS ♦ 


DIRERR 


<ERR0R 


ABORTING OFFSPRINGS 


100 




♦ END 


START 
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Using Directives for Intertask Communication 



SOLUTION 



4 
5 
6 
7 
8 
9 
10 
11. 
12 
13 
14 
15 
16 
1? 
.1.8 
19 

20 
21 
22 
23 
24 
25 
26 
'?'? 

20 
29 
30 
31. 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41. 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦ TITLE LEX45B 

♦ I DENT /Ol/ 
♦ENABL LC 



5 Enable lower C3se 



File L.EX45B*MAC 



Solution to Module 4? Lab Exercise 5 
offspring task 



Part Br 



This task is spawned by 
status every 5 seconds? 
(6 emitsy then an exit). 



LEX45A* It emits a negative 
then exits after 30 seconds 



If an emit status fails because this task was not 
connected to the parent* another emit status will be 
tried 5 seconds later* Two consecutive failures cause 
this task to exit with an error message* 

This task must be installed under task name LEX45B* 

♦ MC ALL EMST*S tQl 0W$C t WTSESC * MRKT$C r EXIT*S 
♦MCALL DIRERR 



NCNCT 



NCNCTL 



START X 



♦ ASCI I 

♦ BYTE 

♦ ASCI I /Wll. 
♦ -NCNCT 

♦ EVEN 



/LEX45B NOT CONNECTED 
15 y 12 

TRY AGAIN 



TO ANY PARENT/ 
IN 5 SECONDS/ 



EMST 



1* 



CLR 
CLR 



MOM 

DEC 
BMI 

MRKT*C 

BCS 

DEC 

EMST*S 

BCS 

CLR 

BR 

CMP 

BNE 



R0 
Rl 



*6yR3 
R3 

EXIT 
1 f 5 f 2 

ERR1 
R0 

yRO 

1$ 

Rl 

WAIT 

$DSW»#IE* ITS 

ERR2 



RO ~ exit status 

Rl ~ means l3st 
attempt to emit status 
sueeeded* RO < means 
it failed because we 
were not connected 

R3 = number of emits 
yet to be issued 

Set timer (again)? 

No r Just exit 

Set timer for 5 seconds 

Use status < when 

emitting 
Emit to parent 
Failed* Why? 
Note success 
Wait for 5 sees to pass 
Failed because not 

connected? 
Any other reason* ouit 
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Using Directives for Intertask Communication 



SOLUTION 



19 


C 






20 




INTEGER DSWflEITS 




21 




DATA IEITS/-8/ 


! Error mnemonic 


22 




L0GICAL*1 ERLAST 


! Flas* if last EMST 


23 


C 




! failed because we were 


24 


C 




! not connected 


25 




DATA ERLAST/ ♦ FALSE ♦ / 




26 


C 






ny 




DO 50 r 1=1*6 


! Issue 6 EMSTs 


2 {3 




CALL. MARK <l>5»2rDSU) 


! Set timer for 5 seconds 


29 




IF (DSW*LT*0) GOTO 900 




30 




CALL EMST( r (-1 ) >DSW> 


! Emit to parent 


31 




IF (DSW*LT*0) GOTO 20 


! Failed* Why? 


32 




ERLAST = ♦ FALSE* 


! Note success 


33 




GOTO 30 


! Wait for 5 sees to pass 


34 


20 


IF (DSW*NE* IEITS) GOTO 


910 ! Failed for reason 


35 


C 




! other than not 


36 


C 




! connected 


37 




IF (ERLAST) GOTO 910 


! Failed last time too? 


38 


C 




! Then <3ive up* 


39 




ERLAST « ♦TRUE* 


! Else note we failed 


40 






! this time 


41 


C 




! And announce the 


42 


C 




! problem* 


43 




TYPE 25 




44 


25 


FORMAT ( 'LEX45B NOT CONNECTED TO ANY PARENT ' / 


45 




1 ' WILL TRY AGAIN IN 5 


SECONDS ' ) 


46 


C 




! And try a3a in in 5 sees 


47 


30 


CALL WAITFR(1>DSW) 


! Wait for 5 sees to pass 


48 




IF (DSW*LT*0) GOTO 920 




49 


50 


CONTINUE 




50 




CALL EXIT 


! Exit (with success) 


51 


C 






52 


C Directive errors 




53 


C 






54 


900 


TYPE * f ' ERROR ON MRK'T ♦ 


DSW = ' y DSW 


55 




GOTO 1000 




56 


910 


TYPE *» 'ERROR EMITTING 


TO PARENT ♦ DSW * ',DSW 


57 




GOTO 1000 




58 


920 


TYPE *, 'ERROR ON WAITFR* DSW = 'yDSW 


59 


1000 


CALL EXIT 




60 




END 
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Memory Management Concepts 



TEST/EXERCISE 



Write ' M ' if the statement applies to mapped systems, 'U' if 
it applies to unmapped systems, or 'M,U* if it applies to 
both. 

a. Physical addresses up to 32K words accessible with 

16-bit addressing. 

b. Physical addresses up to 128K words accessible with 

18-bit addressing. 

c. Program relocation possible without having to program 

or task-build again. 

d. Detection of memory protection violations. 

e. Program executes only at physical addresses that match 

the virtual addresses created by the task builder. 

f. Virtual address limit of 32K words. 



Fill in the headings and the missing values in Figure 1. 
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Memory Management Concepts 



SOLUTION 



Write ' M' if the statement applies to mapped systems, 'U' if 
it applies to unmapped systems, or 'M,U* if it applies to 
both. 

U a. Physical addresses up to 32K words accessible with 
16-bit addressing. (M is also acceptable since 32K 
words is the limit of 16-bit addressing even on a 
mapped system.) 

M b. Physical addresses up to 128K words accessible with 
18-bit addressing. 

M c. Program relocation possible without having to program 
or task-build again. 

M d. Detection of memory protection violations. 

U e . Program executes only at physical addresses that match 
the virtual addresses created by the task builder. 

M, U f . Virtual address limit of 32K words. 

Fill in the headings and the missing values in Figure 1. 
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Overlaying Techniques 



TEST/EXERCISE 



The following is an output display from a task. 

MAIN CALLING SUBROUTINE G 
G CALLING SUBROUTINE Gl 
Gl RUNNING 

MAIN CALLING SUBROUTINE HI 
HI RUNNING 

MAIN CALLING SUBROUTINE H 
H CALLING SUBROUTINE HI 
HI RUNNING 

H CALLING SUBROUTINE H2 
H2 RUNNING 
MAIN EXITING 

The calling sequence parallels the output display. 

1. Draw an overlay tree diagram or a memory allocation diagram 
for a possible overlay structure for the task. 



2. Write the modules MAIN, G, Gl, H, HI, and H2. Assemble or 
compile each one. 

3. Task-build and run the task without overlays. Obtain a map. 

4. Task-build and run the task with all disk-resident overlays. 
Obtain a map. 

5. Task-build and run the task with all memory-resident overlays. 
Obtain a map. 
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Overlaying Techniques 



SOLUTION 

The following is an output display from a task. 

MAIN CALLING SUBROUTINE G 
G CALLING SUBROUTINE Gl 
Gl RUNNING 

MAIN CALLING SUBROUTINE HI 
HI RUNNING 

MAIN CALLING SUBROUTINE H 
H CALLING SUBROUTINE HI 
HI RUNNING 

H CALLING SUBROUTINE H2 
H2 RUNNING 
MAIN EXITING 

The calling sequence parallels the output display. 

1. Draw an overlay tree diagram or a memory allocation diagram 
for a possible overlay structure for the task. 



OVERLAY TREE 

G1 H1 H2 



MEMORY ALLOCATION 
DIAGRAM 



G1 


H1 H2 


G 


H 


MAIN 



MAIN 



TK-7744 
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Overlaying Techniques 
SOLUTION 



1 PROGRAM MAIN 

2 C 

3 C File LEX6A.FTN 

4 C 

5 C Mainline routine for Module 6y Lab Exercises 1-6* 

6 C Illustrate different overlays and their effects* 

7 C 

8 C For each routine!' type message then call routine 

9 C 

10 TYPE * y "MAIN CALLING SUBROUTINE G ' 

11 CALL G 

12 TYPE *y'MAl'N CALLING SUBROUTINE Hi' 

13 CALL HI 

14 TYPE # y "MAIN CALLING SUBROUTINE H' 

15 CALL H 

16 TYPE * y ' MAIN EXITING ' 

17 CALL EXIT 
IS END 



4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 



♦TITLE G 

♦ I DENT /01/ 

♦ ENABL LC 

y 

y File LEX6B ♦ MAC 



y Enable lower case 



y Subroutine for Module 6y Lab Exercises 1-6* 

y Illustrate different overlays and their effects* 



♦ GLOBL Gl 

♦ GLOBL IOFAIL 

♦ MCALL GI0W*C 



y Subroutine called 
y Error routine 



y Messages 

y 

CG1MS: ♦ASCII /G CALLING SUBROUTINE Gl/ 
CGI ML = ♦ -CGI MS 

♦ EVEN 

y 

y Type message then call routine 
y 

Git QI0W*C I0*WMBy5yly y y y <CG1 MS y CG1ML y 40> 

BCS ERROR 

CALL Gl 

RETURN 
error: JMP IOFAIL 

♦ END 
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Overlaying Techniques 
SOLUTION 



1 SUBROUTINE Gl 

2 C 

3 C File? LEX6C ♦ FTN 

4 C 

5 C Subroutine for Module 6r Lab Exercises 1-6 ♦ 

6 C Illustrate different overlays 3nd their effects* 

7 C 

8 C Type message then return 

9 C 

10 TYPE *y 'Gl RUNNING ' 

11 RETURN 

12 END 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 



♦TITLE H 

♦ I DENT /01/ 

♦ENABL LC 

y 

f File LEX6D.MAC 



f Enable lower case 



i Subroutine for Module 6* Lab Exercises 1-6* 

y Illustrate different overlays and their effects* 



» GLOBL H1»H2 
♦ GLOBL I0FAIL 
♦ MCALL QI0W*C 



) Subroutines called 
y Error routine 



f Messages 
r 

CHI MS : .ASCII /H CALLING SUBROUTINE HI/ 
CHI ML = .-CHI MS 

CH2MS i .ASCII /H CALLING SUBROUTINE H2/ 
CH2ML = . -CH2MS 
.EVEN 

? Type message then call routine 

i 

Hi i 



ERROR 



QI0W*C 

BCS 

CALL 

QI0W$C 

BCS 

CALL 

RETURN 

J MP 

.END 



lO.WVBySyly y y y <CHlMSyCHlMI_y40> 
ERROR 
HI 

lO.WVBySyl r > r y <CH2MS r CH2ML y 40> 

ERROR 

H2 

IOFAIL 
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Overlaying Techniques 
SOLUTION 



1 SUBROUTINE HI 

2 C 

3 C File LEX6E ♦ FTN 

4 C 

5 C Subroutine for Module 6» Lab Exercises 1-6* 

6 C Illustrate different overlays 3nd their effects* 

7 C 

8 C Type message then return 

9 C 

10 TYPE *y'Hl RUNNING ' 

1 1 RETURN 

12 END 



6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
.1.7 
18 
19 
20 
21 

23 
24 
2 c: j 



♦TITLE H2 
♦I DENT /01/ 
♦ENABL I...C 

? File LEX6F ♦ MAC 



? Enable lower case 



r Subroutine for Module 6r Lab Exercises 1-6* 

v Illustrate different overlays 3nd their effects 



♦GLOBL IOFAIL 
♦MCALL QI0W*C 



? Error routine 



f Messages 
r 

H2RUN * ♦ ASCI I /H2 RUNNING/ 
H2RUNL = ♦-H2RUN 

♦ EVEN 

y 

? Type message then return 
? 

112:: QI0W*C I0*UVBr5yl r ? f r<H2RUN>H2RUNL>4<» 
BCS ERROR- 
RETURN 

error: JMP IOFAIL 

♦ END 



1 SUBROUTINE H2 

2 C 

3 C File LEX6F*FTN 

4 C 

5 C Subroutine for Module 6r Lab Exercises 1-6* 

6 C Illustrate different overlays and their effects* 

7 C 

8 C Type message then return 

9 C 

10 TYPE *y'H2 RUNNING ' 

11 RETURN 

12 END 
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Overlaying Techniques 
SOLUTION 



i Module Ay Lab Exercise 4 

V 

r »ODL file for build ins! MACRO- 11 with all disk resident 
v overlays 

♦ ROOT LEXA A-PROGSUBS/LB-* < LEXAB-LEXAC , OVRH ) 
OVRHJ ♦ FCTR LEXAD--< LEXAE y LEXAF) 

i LEX 6 A MAIN 

? LEXAB = G 

r LEX AC = : Gl 

? LEX AD = H 

9 LEXAE * HI 

i LEX A I" H2 

y 

♦ END 



v Module Ay Lab Exercise 4 
? 

9 »ODL file for building FORTRAN with all disk-resident 
? overlays 

♦ ROOT LEXAA-FL IB-* < LEXAB-LEXAC-FL IB y HSEGS ) 
HSEGS * . F C T R L E X A D - F L. I B - < L E X A E - F L I B y L E X A F ~ F LIB) 
FLIBt .FCTR LB? CI y 1ZIF4P0TS/LB 



LEXAA 
LEXAB 
LEXAC 
LEX AD 
LEXAE 
LEXAF 



MAIN 
G 

Gl 
H 

HI 

H2 
END 



y Module Ay Lab Exercise 5 
y 

y »ODL file for MACRO- 11 with all memory- resident 
? overlays 

♦ ROOT LEX AA -PROGSUBS/LB-* ! < LEXAB-LEXAC r Ov"RH ) 
OVRHS .FCTR LEXAD-! (LEXAE y LEXAF) 

v LEXAA = MAIN 

r LEXAB = 6 

y LEXAC = Gl 

9 LEX AD = H 

* LEXAE = Hi 

r LEXAF = H2 

♦ END 



73 



Overlaying Techniques 



SOLUTION 



Use the map to fill in the following table: 

Type of Starting Virtual Starting Virtual 

Overlay Address of G Address of HI 

No Overlays 

All 

Disk-Resident Answers will vary depending on 

Overlays students' particular solution. 

All 

Memory-Resident 
Overlays 

Di sk-Resident 
and Memory- 
Resident 
Overlays 



? Module 6y Lab Exercise 8 

? ♦ODL file in MACRO- 11 to place TOTAL in an overlay 
v sesiment ♦ 

? All overlays are disk-resident 

♦ ROOT MAIN~*<A--< J0B1 , JOBXX) >Bf TOTAL) 

♦ END 



? Module 6 v Lab Exercise 8 
y 

} *ODL file in FORTRAN to place TOTAL in an overlay 
? segment* 

f All overlays are disk-resident 

♦ ROOT MAIN--FI_1'B~#( OVRA y B--FLIB » TOTAL--FLIB > 
OVRAJ ♦ FCTR A~FLlB-( JOBl-FLIBr JOBXX -FLIB) 

flib: *fctr lb:ci»i3F4pots/lb 

♦ END 
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Overlaying Techniques 
SOLUTION 



51 


START ♦ 


QI0W*C 


I0*Wv"By5y 


1 y 


fir 


:!MES1 y L.MES1 y 40> y Write MES1 


52 




CALL 


A 






y Call subroutine A 


53 




CALL 


RTOTAL 






y Call routine to yyEX 


54 












y display running J J EX 


55 












y total ? y EX 


56 




QI0W*C 


I0*Wv"By5y 


It 




c!MES2yLMES2y40> y Write MES2 


57 




CALL 


B 






y Call subroutine B 


nJ O 


y Oct t 


up for loop 








59 




MOV 


#3>R4 






y Counter 


60 


loop: 


QI0W$C 


I0*WVBy5y 


1 t 


y y y •: 


:.MES3yLMES3y40> y Write MES3 


61 




CLR 


ANS 






« PI iaar jancuor *ir*i r*s>c:cj 
" wlcrdl ol 1 We 1 J. II C c> fcr 


62 












y of no operation 


63 




CALL 


A 






y Call subroutine A 


64 




CALL 


RTOTAL 






? Call routine to yyEX 


65 












? display running yyEX 


66 












y total y y EX 


67 




SOB 


R4H..00P 






y Decrement counter and 


68 












y loop back until done 


69 




QI0W*C 


I0*WUBy5y 


1 r 


! H' : 


::MES4yLMES4y40> ? Write MES4 


70 




CALL 


TOTAL 






y C3ll routine to 


71 












y display grand total 


72 




QI0W*C 


I0*WVB>5» 


1 t 


y y y ■'■ 


::MES5yLMES5y40> y Write MESS 


73 




EXIT*S 








y Exit 


74 




♦ END START 








1 


c 


PROGRAM 


MAIN 








3 


C FILE 


LEX69A ♦ FTN 






M EX 



4 C 

5 C Modified to call RTOTAL to display the running ! ! EX 

6 C after each C3ll to A ! ! EX 

7 C 

8 C This program prints a message and then calls subroutine 

9 C A* Subroutine A asks whether to perform Job 1 or Job 2*P 

10 C It then calls either subroutine JOB! or J0B2 which 

11 C performs the operation and displays the results* MAIN 

12 C then calls subroutine B which displays a message* MAIN 

13 C then calls subroutine A 3 more timesy keeping a grand 

14 C total of the operations* Final lyy it displays the 

15 C grand total and exits* 

16 C 

17 C Task-build instructions* Use LEX69A*0DL as the input!! EX 
1.8 C file for RTOTAL in the root* Use LEX69B*0DL as the ! ! EX 
.1.9 C input file for RTOTAL in the best overlay segment ! ! EX 
20 C 
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Overlaying Techniques 
SOLUTION 



♦TITLE RTOTAL 
♦ I DENT /01/ 
♦ENABL LC 

r 

> FILE LEX69B ♦ MAC 



$ Enable lower case 



i Subroutine to print the running total 



8 
9 
10 
.11 
12 
13 
14 
15 
16 
17 
18 
19 

20 
21 
22 
23 
24 



♦ MCALL 
♦NLIST 

rtofmt: .asciz 
rtotbf: ♦ blkb 

♦ EVEN 
♦NLIST 

rtotal MOV 

MOV 
MOV 

CALL 
QI0W*S 

RETURN 

♦ END 



QIOW$S t 

BEX ? 

i 

/THE TOTAL SO FAR 
100* i 

BEX r 

♦RTOTBF .» RO i 
#RTOFMT r Rl r 
#T0T»R2 t 
$EDMSG r 
#10 ♦ WVB>#5f #1 ttft- 



External system macros 
Do not list binary 

extensions 
IS %D ♦ / r Fa rmat s t r :i. rig 
Output buffer 

List binary extensions 
Set up for * EDMS 6 



Edit message 
:#RT0TBFf Rl t*40> 

Print it 



1 SUBROUTINE RTOTAL 

2 C 

3 C FILE LEX69B+FTN 

4 C 

5 C Subroutine to print the running total 



6 C 

7 COMMON /T0TC0M/T0T 

8 INTEGER TOT 

9 TYPE 5 1 TOT 

10 5 FORMAT ( ' THE TOTAL SO FAR IS'y I4y' t '> 

11 RETURN 

12 END 



r Module 6f Lab Exercise 9 
? 

5 ♦ODL file in MACRO-llr placing RTOTAL in the root 

P segment for testing 

9 All overlays are memory- resident 

♦ ROOT LEX69A-LEX A9B-* ! < A- ! < JOB 1 r JOBXX ) y B r TOTAL ) 
? LEX69A ••= MAIN modified to call RTOTAL 

? LEX69B = RTOTAL 

♦ END 
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Static Regions 



TEST/EXERCISE 



Create an initialized resident common (size: 32(10) blocks = 
1024(10) words, contents: 25(10) in each word). Check with 
your course administrator to find out where to place the 
common type partition. Write two tasks, one that modifies all 
values in the common, and one that reads the values and 
displays them. 

Create a resident library using the supplied FORTRAN callable 
subroutines AADD, SUBB, MULL and DIW (all in LIB. MAC) . Write 
a task that calls one or more of the routines. For example, 
write a task that asks for four numbers (A, B, C, and D) and 
then computes and displays (A * B) + (C * D) = answer. 
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Static Regions 



SOLUTION 



1. 1 ♦ TITLE LEX71A 

2 ♦ I DENT /01/ 

3 .ENABL LC r Enable lower case 

4 t f 

5 ? File LEX71 A * MAC 

6 5 

7 y Program which creates and initializes a -common region 
(3 y which will be referenced using overlaid Psects. 

9 t 

10 y Size 1024* words? contents all 25 "s 

11 f 

12 ? Task-build instructions i Must include /SHAREABLE I COMMON 

13 r and /NOHEADER switches? STACK=0 and PAR=C0MWP options* 

14 y Must create .STB file* M3« be /CODE* PIC or absolute 

15 ? (default)* 
.1.6 ? 

17 y The code is placed in a Psect named MYDATA 
18 

19 .PSECT MYDATA DyGBLyOVR t Defaults RELyRW 

20 ♦REPT 1024* y Repeat count 

21 .WORD 25. r Word of 25(10) 

22 .ENDR y End repeat range 

23 .END 



1 BLOCK DATA LEX71A 

2 C 

3 C File LEX71 A ♦ FTN 

4 C 

5 C Program to create and initialize a resident common 

6 C 

7 C Size is 1024 wordsy initialized with all 25 's 

8 C 

9 C Task-build instructions. Must include /SHAREABLE * COMMON 

10 C and /NOHEADER switches? STACK=0 and PAR=C0MWP options. 

11 C Must create .STB file. Maw be /CODE* PIC or absolute 

12 C (the default). 0TS library NOT required. 

13 C 

14 COMMON /MYDATA/ 1(1024) 

15 DATA I / 1024*25/ 

16 END 
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Static Regions 
SOLUTION 



50 


ERROR i: MOVB 


1'OSByRO 


y 


Extend si sin on 


I/O 


5.1 


MOV 


ROyARG 


y 


status and pis 


ce in 


52 






y 


ar# block 




53 


MOV 


♦FERR2 y Rl 


y 


Addr of format 


st r ins* 


54 


setup: MOV 


#BUFF y RO 


y 


Addr of output 


buffer 


55 


MOV 


#ARG yR2 


y 


Addr o f a r s$ u in e n 


t block 


56 


CALL 


*EDMSG 


y 


Edit inessasfe 




57 


QIOW*S 


#10* WVBy#5y#.l y 


y y y 


:.#BUFFyR:l. y#40> t 


Write 


58 






y 


message 




59 


EXIT*S 




y 


Exit 




60 


♦ END 


START 








1 


PROGRAM 


L.EX71B 









3 
4 

5 
6 
7 
8 

9 
10 
11 

12 
13 
14 
15 
16 
1 7 
18 
19 
20 
21 
22 
23 
24 
25 



File LEX71EUFTN 

Task to decrement each word in the static common 
resJion L.EX71A* It uses 3 COMMON to reference 
the data* 

Task-bui Id instructions i 

LINK/MAP/OPTION LEX71ByLB* CI r 1 3F0R0TS/LIBRARY 
Option? RESC0M : ~LEX71 A/RW 
Option? <RET> 

COMMON /MYDATA/ L(1024)! Common to reference 

! shared region 

Decrement values 

DO 5 K>-lyl024 

L(K)=L(K)-1 

CONTINUE 

WRITE (5yl0) ? Display done message 

FORMAT ( ' LEX71B HAS MODIFIED THE VALUES IN THE 

1 COMMON LEX71 A ' ) 
CALL EXIT 
END 
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Static Regions 



SOLUTION 



51 J Error code 

52 ERROR i MOM *DSWyARG y Move DSW to ars* block 

53 MOM #FERRlyR.1. t Addr of format string 

54 BR SETUP y Branch to $ ED MSG code 

55 ERROR 1 t MO MB lOSByRO r Extend si an on I/O 

56 MOM ROvARG y status and place in 

57 y ar.?J block 

58 MOM *FERR2yRl y Addr of format strinss 

59 SETUP: MOM *BUFF y RO ? Addr of output buffer 

60 MOM #ARGyR2 y Addr of argument block 
6.1. CALL *EDMSG P Edit message 

62 QI0W$S #I0»WMBy#5y#l y y y y<#BUFFyRl y#40> y Write 

63 y message 

64 EXIT$S ? Exit 

65 ♦ END START 



1 

2 


C 




PROGRAM LEX71C 


3 


C 


File 


LEX71C.FTN 


4 


C 






5 


C 


Task 


to read data from the static common region LEX71A 


6 


C 


and 


print it out at TIJ» It uses a COMMON to reference 


7 


C 


the 


data ♦ 


8 


C 






9 


c 


Task 


- bui Id instructions I 


10 


c 






11 


c 




LINK/MAP/OPTION LEX71C y LB t C 1 y 1 3F0R0TS/L IBRARY 


12 


c 




p t i o n ? R E SC0M-L E X 7 1 A / R 


13 


c 




Option? <RET> 


14 


c 






15 






COMMON /MYDATA/ L<1024>! Common to reference 


16 


c 




! shared region 


1 7 


c 


Loop 


through to display resiony 8 numbers on a line 


18 






DO 50 J •= Iyl024y8 


19 






WRITE (5yl0) <L(K) »K=J» J+7) ! Write values 


20 


10 


FORMAT (' ',I2»7I8> 


21 


50 




CONTINUE 


22 






CALL EXIT 


23 






END 
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Static Regions 
SOLUTION 



51 


addarg: 


♦ WORD 


3 


y 


For ADD 


52 




♦ WORD 


MURES 1 


y 


First MUL result 


53 




♦ WORD 


MULRES 


y 


Second result 


54 




♦ WORD 


GRTOT 


y 


Grand total 


55 
56 


y ASCII 


buffer 


table ♦ Initially 


each entry in this table 


57 


v consists of 


the address of a 


prompt string followed by 


58 


? the a 


ddress 


of the buffer to 


store the inputs After a 


59 


y string is input v however? the 


prompt strinsi address is 


60 


? replaced by 


the length of the 


input string* This 


61 


r table 


y with 


the addition of the 


final value GRTOT y then 


62 


y serve 


s as the $EDMSG argument 


block* 


63 


edmarg: 










64 


ABTBL t 


.WORD 


APRMT y ASCA 






65 




* WORD 


BPRMTy ASCB 






66 


CDTBL t 


♦ WORD 


CPRMTyASCC 






67 




♦ WORD 


DPRMTy ASCD 






68 


GRTOT t 


♦ WORD 




y 


Grand total (numeric 


69 








y 


value is inserted 


70 








y 


directly into $EDMSG 


71 








5 


block ) 


72 


y 










73 


t Other 


numeric values 






74 


Ml ♦ 


♦ WORD 




y 


First MUL argument 


75 


M2J 


♦ WORD 




y 


Second MUL argument 


76 


MURES i : 


♦ WORD 




y 


First MUL result 


77 


MULRES* 


♦ WORD 




y 


MUL result 


78 












79 


RDPRMT t 


QI0W* 


I0»RPRy5vl.» ylOSBx 


y<y7y y yPLENy ' $> 


80 


iosb: 


♦ BLKW 


^« 






81 












82 












83 


i Code 










84 


? 










85 


START i 


QI0W*C 


I0*WVBy5y.1. y y y y< 


HDRMS y HDRML r 40> y Identify 


86 




MOV 


#MlyR5 


y 


R5 => location to store 


87 








y 


binary input values 


88 




MOV 


♦RDPRMT y R4 


y 


R4 => "read with 


89 








y 


prompt" DPB 


90 




MOM 


♦ABTBL y R3 


y 


R3 "> ASCII buffer table 


91 




CALL 


GETINP 


y 


Get A 


92 




CALL 


GETINP 


y 


Get B 


93 




MOV 


♦MULARG r R5 


y 


R5 => MUL arg block 


94 




CALL 


MULL 


y 


Do first multiply 


95 




MOV 


MULRES y MURES 1 


y 


Save result 


96 




MOV 


♦Ml yR5 


y 


Reset registers 


97 




MOV 


♦RDPRMT yR4 


y 


(FORTRAN calling 


98 




MOV 


♦CDTBL yR3 


y 


convention does not 


99 








y 


guarantee they are 


.00 








y 


preserved* ) 
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Static Regions 



SOLUTION 



1 PROGRAM LEX72 

2 C + 

3 C File LEX72*FTN 

4 C 

5 C Solution to Module 7y Lab Exercise 2 

6 C 

7 C Task computes sum of products us ins! resident library 

8 C routines* 



9 C 

10 C Task build instructions* 

11 C 

12 C LINK/MAP/OPTIONS LEX72 yLB i C 1 y 1 DF4P0TS/LIB 

13 C Option? RESLIB=LIB/R0 

14 C- 

15 INTEGER A>B»C»Di> MURES 1 y MURES2 y GRTGT 

16 C ASCII bytes to make prompting code cleaner 

17 BYTE ASC A y ASCB r ASCC y ASCD 

18 DATA ASCAyASCBv ASCC y ASCD/ ' A ' y 'B' y 'C r 'D V 

19 C 

20 TYPE 5 

21 5 FORMAT (' TASK WILL COMPUTE < A*B)+ (C*D ) '/ 

22 1 ' ENTER NUMBERS IN DECIMAL*') 

23 C FORMAT statements used repeatedly below I 

24 15 FORMAT C$ENTER SA1»'J ') 

25 25 FORMAT <I6) 

26 TYPE 15'yASCA ! Prompt for 

27 ACCEPT 25 y A ! and input A 

28 TYPE 15 y ASCB ! Prompt for 

29 ACCEPT 25 yB ! and input B 

30 CALL MUL.L( AyByMURESl ) ! MURES1 = A*B 

31 TYPE 15 y ASCC » Prompt for 

32 ACCEPT 25 yC ! and input C 

33 TYPE 15 y ASCD ! Prompt for 

34 ACCEPT 25 yD ! and input D 

35 CALL MULL ( C y D y MURES2 ) ! MURES2 = C*D 

36 CALL A ADD (MURES 1 y MURES2 y GRTGT ) ! GRTOT « sum 

37 TYPE 35 y A y B > C y D y GRTOT 

38 35 FORMAT (' CyI6y' * M6r') + ' * / yI6y / ) = '*I6> 

39 CALL EXIT 

40 END 
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Dynamic Regions 



TEST/EXERCISE 



Referring to Exercise 1 of Module 7 (Static Regions) , modify 
the tasks that reference the common so that they both map to 
the common dynamically using the memory management directives. 

Write a task that creates a dynamic region two blocks long, 
fills it with a character typed in at the terminal, and leaves 
it in existence on exit. Write a second task that modifies 
one value in the region, then displays all the values in the 
region at the terminal, and finally deletes the region. 

Modify SNDREF so that it sends the region by reference to a 

second receiver task, in addition to RCVREF. Write the second 

receiver task, which should modify values in the region and 

then display the values in the region at the terminal. 
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Dynamic Regions 



SOLUTION 



l. 



6 
7 
8 
9 
10 
11 
12 
13 
.1.4 

15 

.1. 6 

17 
■ 18 
19 

20 

21 
"> "> 

23 
24 
25 
26 
27 
28 

30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 

47 
48 
49 
50 



y + 



♦TITLE LEX81B 
♦ I DENT /01/ 

♦ENABL LC y En3ble lower case 

File LEX81B»MAC 

LEX71B modified to use memory management directives 

Program to attach to the existing region LEX71Ay create 
a virtual address window (mapped on creation))' decrement 
all values in the region by 1 r detach from the region 
and exit* 

Assemble and task-build instructions* 

>MACR0/LIST LB? CI 1 1 L1PR0GMACS/LIBRARY r dev t Cuf d.lLEX81B 
>L INK/MAP/OPTION LEX81B y LB : C 1 y 1 3PRQGSUBS/L IBRARY 
>0>tion? WNDWS=1 
>0ption? <RET> 



rdb: 



win: 
wdb : 

y 



iosb: 
w 

done : 

LD0NE 

start: 



♦ MCALL. 
♦ MCALL 
* MCALL 
RDBBK$ 

Define 



EX I T$S f RDBBK$ y WDBBK$ t ATRG$C i System 
CRAW**DTRG*S>DIR*>QI0W*S y macros 
DIRERR y I0ERR r Supplied macros 
32 ♦ t LEX7 1 A y LEX7 1 A y <RS ♦ WRT ! RS . RED> 
region with* 
Size - 32* (32* word blocks) 

Name = LEX71A 

Partition = LEX71A 

Attach with read and write access 



CRAW* 



WDB 



?DPB for create address window 



WDBBK* 7 y 32 * y y y 32 * y <WS ♦ MAP ! WS ♦ RED ! WS ♦ WRT? 
Define window with: 

APR =7 

Size 

Offset in region 
Length in region 



32* (32* word blocks) 
(32* word blocks) 
32* (32* word blocks) 



♦ BLK'W 

^1024* 

♦ASCII 

♦ASCII 

=.-D0NE 

ATRG*C 

BCS 
MOV 

DIR* 

BCS 



Map on create with read and write access 

2 5 1/0 status block 

y * of words in region 
/LEX81B HAS MODIFIED THE VALUES/ t Done 
/ IN LEX71A/ y message 



RDB 
ERR1 

RDB+R * G I D y WDB + W ♦ NR I D 



y Attach to region 
y Check for error 



♦ WIN 

ERR 2 



Move region ID 
y into WDB 
y Create window 
y Check for error 
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Dynamic Regions 



SOLUTION 



29 C WDB ~ Window definition block with the following properties J 

30 C APR 7 

31 C Size 32 (10) (32. -word blocks) 

32 C Offset in region (32* -word blocks) 

33 C Length of window 32 (10) (32* -word blocks) 

34 C Map on create with read and write access 

35 C Initialize the WDB 

36 DATA WDB /"3400*0*32*0*0*32* "203*0/ 

37 C 

38 C Attach region 

39 CALL ATRG ( RDB * IDS ) 

40 C Check for error on attach 

41 IF (IDS .LT. 0) GOTO 100 

42 C Move region id to WDB 

43 WDB(4)=RDB(1) 

44 C Create and map window 

45 CALL CRAW < WDB* IDS) 

46 C Check for error 

47 IF (IDS .LT. 0) GOTO 200 

48 C Decrement values 

49 DO 50 K=l*1024 

50 I DATA ( K ) =IDATA ( K ) -1 

51 50 CONTINUE 

52 C Detach from region and delete it 

53 CALL DTRG ( RDB * IDS) 

54 C Check for error 

55 IF (IDS .LT. 0) GOTO 300 

56 C And Jump to exit 

57 WRITE (5*60) 

58 60 FORMAT ( ' LEX81B HAS MODIFIED THE VALUES IN 

59 1 THE COMMON LEX71A ' ) 

60 GOTO 500 

61 C 

62 C Error messages 

63 100 WRITE (5*101) IDS 

64 101 FORMAT (' ERROR ATTACHING TO REGION* DSW ='*I4) 

65 GOTO 500 

66 200 WRITE (5*201) IDS 

67 201 FORMAT (' ERROR IN CREATING WINDOW* DSW ='*I4) 

68 GOTO 500 

69 300 WRITE (5*301) IDS 

70 301 FORMAT (' ERROR DETACHING FROM REGION* DSW ='*I4) 

71 C 

72 500 CALL EXIT 

73 END 
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Dynamic Regions 
SOLUTION 



52 




DCS 


ERR2 


5 Check for error 


53 




MOV 


#1 60000 >R2 


i Set base addr in region 


54 




MOV 


#N ? R5 


9 Loop count 


55 


loop: 


MOV 


#BUFF y RO 


9 Set up for $EDMSG 


56 




MOV 


#FMT y Rl 




57 




CALL 


$EDMSG 


9 Edit data 


58 




GIOW*S 


#I0*WVBy#5r#l f , 


#IOSB> 9 <*BUFF»R1 y*40> 


5? 








i Write data 


60 




BCS 


ERR3D 


9 Check for dir error 


61 




TSTB 


IOSB 


9 Check for I/O error 


62 




BLT 


ERR3I 


9 Branch on error 


63 




SOB 


RSyLOOP 


f Print the line 


64 


done: 


DTRG$S 


#RDB 


i Detach from resiion 


65 




BCS 


ERR4 


9 Check for error 


66 




EXIT*S 






67 


i Error 


h3ndl ins 


S code 




68 


ERR1 : 


DIRERR 


< ERROR ATTACHING TO REGIONS- 


69 


ERR2 : 


DIRERR 


TERROR CREATING 


WINDOW AND MAPPING!:-- 


70 


ERR 3Dt 


DIRERR 


<ERROR WRITING 


DATA> 


71 


ERR 3 I : 


IOERR 


#IOSBy<ERRQR WRITING data> 


72 


ERR 4 : 


DIRERR 


< ERR OR DETACHING FROM REGIONS- 


73 




♦ END 


START 





PROGRAM LEX81C 



3 


C 


4 


C 


5 


c 


6 
7 


c 

C 


8 


c 


9 


c 


10 


c 


11 


c 


12 


c 


13 


c 


14 


c 


15 




16 


c 


17 




18 


c 


19 


c 


20 


c 


21 
22 


c 
c 


23 


c 


24 


c 


25 


c 







VSECT=DATA : 1 60000 : 20000 
WNDWS^l 

INTEGER RDB<8) y WDB(8) 
common block will alidn with the 

COMMON /DATA/IDATA( 1024 ) 



Size 32 <10) (32* -word blocks) 

Name LEX71A 

Partition LEX71A 

Protection WO : none 9 S Y : RWED 9 OW : RWED 9 GR : RWED 

Attach with read access 
ilize the RDB 

DATA RDB /0 y 32 9 3RLEX y 3R71 A 9 3RLEX 9 3R71 A r " 000001 y 
1" 170000/ 
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Dynamic Regions 
SOLUTION 



2. 



3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
.1.3 
14 
15 
16 
17 
18 
19 
20 
21 

23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦ TITLE 
♦I DENT 
*ENABL 



LEX82A 

/01/ 

LC 



9 Enable lower case 



y File LEX82A.MAC 



Program to create an named region (attached on 
creation)!' create a virtual address window (mapped on 
creation) r place ASCII data in to region* detach from 
the region and exitv leaving the region in existence* 

Task ~bui Id instructions ♦ 

Include WNDWS~1 option 

♦ MC ALL EXI T*S y RDBBK* y WDBBK* y CRRG$ t CRAW* 
♦ MCALL DTRG*yDIR*yQI0W*SyQI0W*C 



REG i 



RDB : 



WIN* 



CRRG* 



RDB 



?DPB for create region 



Define region with* 
Size 
Name 

Partition 
Protection 

Do not mark for 



= 2 (32* word blocks) 

MYREG 
= GEN 

= W0:None»SYiRWED» 
0U : RUED rGR: RUED 

delete on last detach 



Attach with write and delete access 
RDBBK* 2 y MYREG y GEN y <RS * NDL ! RS ♦ DEL ! RS ♦ WRT ! RS ♦ ATT> y 1 70000 



CRAW* 



WDB 



y DPB for create address window 



Define window with: 
APR 
S i ze 

Offset in region 
Length in region 



7 

2 (32* word blocks) 

(32* word blocks) 

2 (32* word blocks) 



WDB** 
y 

det: 
iosb: 

BUFF i 
MES : 
LEN 
DNMES t 

LDNMES 
? Error 
FCRRER : 

fcrwer: 
fdeter: 



M3P on create with write access 
WDBBK* 7 r 2 y y y 2 y <WS ♦ MAP ! WS ♦ WRT> 

DTRG* RDB y DPB for detaching region 

♦ BLKW 2 ? I/O status block 

♦ BLKB 80* i Input/Output buffer 

♦ ASCI I /ENTER ASCII CHARACTER: / 
♦ - MES 

.ASCII <15>/LEX82A HAS CREATED AND INITIALIZED/ 
♦ASCII / THE REGION/ 
= ♦ -DNMES 
format strings 

♦ASCIZ /ERROR CREATING REGION* DSW = %D*/ 
* ASCIZ /ERROR CREATING WINDOW* DSW = %D*/ 
♦ASCIZ /ERROR DETACHING FROM REGION* DSW = %D*/ 
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Dynamic Regions 
SOLUTION 



101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 



err; 



shoerr: 



MOV 

BR 

MOV 

MOV 
MOV 
CALL 
QIOW*S 

EXIT*S 

♦ END 



#FQ-I2IE»R1 

SHOERR 

#F DETER y Rl 

#BUFFyRO 
#*DSU»R2 
*EDMSG 
*IO,WVBy#I 



y QIO write err message 

? Branch to common code 

r Detach region message 

y Set up for *EDMS6 



t Edit message 
iy*ly t , ><#BUFF*R1»#40> 

5 Display message 
y Exit 



START 



3 
4 

5 
6 
7 
8 
9 
10 
.1. 1 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 



PROGRAM LEX82A 
File LEX82A ♦ FTN 

LE.X82A creates a named region (attached on creation)? 
creates a virtual address window (mapped on creation) r 
places an ASCII character input at TI» at all locations 
in the region y detaches from the region and exits r 
leaving the region in existence* 

Task-build instructions i 

>LINK/MAP/0PTI0NS/C0DEtFPF LEX82AyLBtl.:iy l:lF0R0TS-• 
■•••>/LIBRARY 

Opt ion? VSECT-DATA : 160000 : 20000 
Option? WNDWS==1 
Option? < RETA- 



RDS :::: Region Definition 
f ol lowing properties* 

Size = 
Name = 
Partition = 
Protection -.= 



Block for region with the 



Do not 
Attach 



mark 
with 



for 



= 2 (32. word blocks) 
= MYREG 
= GEN 

= WOtNoneySYfRWED 
0W ♦ RUED y GR ♦ RWED 
delete on last detach 



write and delete access 



UDB ~ Window Definition Block for window with the 
following properties* 

APR = 7 

Size 

Offset in resfion 
Length in resfion 



~ 2 (32* word blocks) 

- (32* word blocks) 

- 2 <32* word blocks) 



Map on create with write access 
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Dynamic Regions 
SOLUTION 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
.1 6 
17 
18 
.1.9 
20 

21 

2 2 

23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦ TITLE LEX82B 
♦I DENT /01/ 

♦ ENABL. LC 



y Enable lower case 



File LEX82B*MAC 



Program to attach to arr existing resfiony create a 
v i r t u a 1 a d d r e s s w :i. n d o w ( in a p p e d o n c r e a t i on) y m o d :i. f w 
the first byte of the region? read ASCII data from the 
re?*3iony detach from the region and mark it for de.letey 
a n d f i n 3 1 1 w e x it* T h e re si i o n will b e d e I e t e d o n 1 a s t 
detach ♦ 

Assemble and task-build instructions? 

>MACR0/LIST LB t t 1 , 1 DPR0GMACS/LIBRARY r dev : Cuf d3- 

->LEX82B 

> L I NK/MA P / P T I ON L E X 8 2 B y L B i L" 1 y 1 1 P R G S UBS/ L I B R A R Y 
> Opt ion? WNDWS-1 

>0ption? <RET> 



♦MCALL E X I T $ S y R D B B K $ ? W D B B K * y A T R G $ C y System 

♦ H C A L I... C R A U) $ y D T R G * S t D I R $ y Q 1 U * S » m a c r o s 

♦ MCALL. tU'RERR y I0ERR y Supplied macros 
RDBBK* y MYREG y GEN , <RS ♦ WRT ! RS . RED ! RS ♦ MDL ! RS , DEL> 
Define region with? 

Size ~ (32* word blocks) 

returned after attach 
Name ~ MYREG 

Partition - GEN 

Mark for delete on last detach 
Attach with ready write and delete access 



rub: 



win; 
udb: 



CRAW* WDB JDPB for create address window 

WDBBK* 7 y 200 y 1 y y <WS . MAP ! WS ♦ RED ! WS ♦ WRT> 
D e f i n e w i n d o w w i t h i 

APR = 7 

Size = 200 (32. word blocks) 

Offset in region ~ (32* word blocks) 
Length in region - (32* word blocks) 

returned when mapped 
Map on create with read and write access 



iosb: ♦BLKW 2 
RSIZ =128* 

start; atrg*c rdb 

BCS ERR1 



f I/O status block 

y Re si ion size in bytes 

y Attach to region 

y Check for error 



MOV R D B + R ♦ G I D y W D B + W ♦ N R I D y Move region ID 

y into WDB 

DIR$ *WIN y Create window 
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Dynamic Regions 
SOLUTION 



.1. 

16 




I NTEGER RDB ( 8 ) y WDB < 8 ) 


17 




BYTE I DATA (128) 


.18 


C 


Th.i. s common block will 3lidn with the address window 


.19 




COMMON /DATA/IDATA 


20 


c 


RDE< "•" Region definition block with the following 


21 


c 


properties* 


22 


c 


Size ( 32 ♦ -word blocks) 


23 


c 


filled in when attached 


24 


c 


Name MY REG 


25 


c 


Partition GEN 


26 


c 


P r o t ec t i on W0 * none y S Y ♦ RWEB y OW i RUED y GR J RUED 


27 


c 


Mark for delete on last detach 


28 


c 


Attach with delete* write and read access 


29 


c 


Initialize the RDB 


30 




DATA RDB /0 v y 3RMYR y 3REG y 3RGENy 3R » "00021 3 f 


3 .1 


c 


1 " 170000/ 


32 
33 


c 


WDB - Window definition block with the following 


34 
35 


c 
c 


properties* 

a r*» r*t "') 

flrh / 


36 


c 


Size 200(8) (32* -word blocks) 


37 


c 


Offset in region (32 ♦-word blocks) 


38 


c 


Length of window (32* -word blocks) 


39 


c 


filled in when mspr-'ed 


40 


c 


Map on create with read access 


4.1 


c 


Initialize the WDB 


42 




DATA WDB /"3400y0y "200y0y0y0y "203*0/ 


43 


c 




44 


c 


Attach region 


45 




CALL ATRG (RDBylDS) 


46 


c 


Check for error on attach 


47 




IF (IDS .LT. 0) GOTO 100 


49 


c 


Move r e*S ion id to WDB 


49 




WDB(4):;-RDB( 1 ) 


50 


c 


Create and map window 


51 




CALL CRAW (WDBylDS) 


52 


c 


C h e c k for error 


53 




IF (IDS ♦ LT ♦ 0) GOTO 200 


54 


c 


Place ASCII Z in first byte 


55 




I DATA ( 1 )«'Z' 


56 


c 


Print contents of region 


57 


10 WRITE <5»il> IDATA 


58 


11 


FORMAT (' 'y64Al) 


59 


C 


Detach from region and delete it 


60 




CALL DTRG (RDBylDS) 


61 


C 


Check for error 


62 




IF (IDS ♦LT. 0) GOTO 300 


63 


c; 


And Jump to exit 


64 




GOTO 500 



107 



Dynamic Regions 
SOLUTION 



3. 



3 
4 

5 
6 
7 
8 
9 

10 

11 
12 
13 
14 
.1.5 
16 
17 
18 
19 
20 
21 
22 
23 



26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 



♦TITLE SNDREF 
♦I DENT 701/ 
♦ENABL LC 



r File LEX83A*MAC 



y Enable lower case 
y y EX 



Modified to send to a 2nd receiver RCVRF2 in yyEX 
addition to RCVREF yyEX 

LEX83A creates a 64-word (2 block) unnamed region and 
fills it with ASCII characters* It then sends the 
region to RCUREFy and then waits for RCVREF to receive 
the region* (This is signalled by event flag #!♦) It 
then prints a message and exits* Since the area is 
n n a m e d y i t i s a u t o m a t i c a 1 1 y deleted when the last 
attached task exits* 

Assemble and task -build instructions* 

>MACR0/LIST LB i C 1 y 1 1PR0GMACS/LIBRARY r dev ♦ L"uf d3~ y yEX 
->LEX83A 

>L INK/MAP/OPTION L.EX83A y LB ♦ C 1 y 1 IIPROGSUBS/LIBRARY 
Option? UNDWS-1 

Install and run instructions* RCVREF must be installed* 
LEX83B must be installed as RCVRF2* Run LEX83A first y 
then run RCUREF and RCURF2 (either one first) 



* MCALI... 

* MCALI... 
♦ MCALL 

* MCALI... 
.NLIST 



QI0W*Cyai0W*SyRQST*C y System macros 
WTSE*C y EXIT*S y RDBBK* t WDBBK* 
CRRG*S y CRAWtS t SREF*C 



DIRERR 
BEX 



Supplied macro 
SUPPRESS DATA 



? Define region with* 



RPR0 
RSTAT 

rdb: 



Size « 2 32- WORD BLOCKS 

Name = none 

Partition ~ GEN 

Protection ~ W0 ♦ none y GR ♦ RUED 

OW:RWEDySY:none 

Attach on create 

Read and write access desired on attach 
= 170017 

= RS ♦ ATT ! RS ♦ RED ! RS ♦ WRT 
RDBBK* 2 y y GEN y RSTAT y RPRO 



109 



Dynamic Regions 
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99 




GI0W*C 


IO.WVB 




2 y ft t <MES2 ? LMES2 y 40S- t D i 


splay 


100 










y mess 


age 


101 




BCS 


6$ 




y Branch on d.ir error 


102 




EXIT*S 






y Exit 




103 


y Error 


code 










104 


i$: 


DIRERR 


< ERR OR 


ON 


CREATE OR ATTACH REGIONS- 




105 


2$: 


DIRERR 


< ERROR 


ON 


CREATE OR MAP WINDOWS- 




106 


3$: 


DIRERR 


< ERR OR 


ON 


SEND BY REFERENCES- 




107 


4$: 


DIRERR 


< ERROR 


ON 


1ST WRITES- 




108 


5* J 


DIRERR 


<ERROR 


ON 


WAIT FORS- 
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6*: 


DIRERR 


< ERR OR 


ON 


2ND WRITES- 




110 


7$: 


DIRERR 


< ERROR 


ON 


2ND SEND BY REFERENCES- 


9 yEX 


111 


S'l> J 


DIRERR 


< ERROR 


ON 


2ND WAIT FORS- 


y yEX 


112 




♦ END 


START 









3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 



PROGRAM SNDREF 
File LEX83A ♦ FTN 

Modified to send the region by reference to RCVRF2 HEX 
in addition to RCVREF HEX 

This program creates a 64-word unnamed region and 
fills it with ASCII characters* It then sends it by 
reference to task RCVREFy and waits for RCVREF to 
receive the region* (This is signalled by event flag 
*!♦) SNDREF then prints a message and exits* Since 
the area is unnamed y it is automatically deleted when 
the last attached task exits* 

Task -bu i 1 d i ns t rue t i ons ♦ 

S LINK/MAP/CODE *FPP/0PT IONS LEX83A y LB t C 1 y 13F0- ! ! EX 

-SPOTS/LIBRARY ! !EX 

Option? WNDWS=1 

Option? v"SECT~DATA * 160000 ♦ 200 

Option? <RET> 

Install 3nd run instructions* RCVREF must be installed* 
LEX83B must be installed under the name RCVRF2. ! ! EX 
Run LEX83A first y then run RCVREF and RCVRF2 (in ! ! EX 
either order) 

RDB == Region definition block with the following 
properties* 

Size 2 32 -word blocks 

Name none 

Partition GEN 

Protect! or. WO : none y S Y : RUED y OW : RWED y 

GRtnone 
Attach on creation 

Read and write access desired on attach 
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Dynamic Regions 



SOLUTION 



85 C Error handling code 

86 100 WRITE (5*110)1 DS 

87 110 FORMAT (' ERROR CREATING REGION * DSW ~ '»I4> 
98 GOTO 600 

89 200 WRITE (5* 210) IDS 

90 210 FORMAT (' ERROR CREATING WINDOW * DSW ~ '*I4) 

91 GOTO 600 

92 400 WRITE (5*410) IDS 

93 410 FORMAT (' ERROR IN SEND-BY -REFERENCE * DSW » '*I4) 

94 GOTO 600 

95 450 WRITE (5*460) IDS 

96 460 FORMAT (' ERROR IN 2ND SEND--BY-REFERENCE * DSW 

97 1 = ' *I4) ! !EX 

98 GOTO 600 ! ! EX 

99 500 WRITE (5* 510) IDS 

100 510 FORMAT ( ' ERROR ON WAIT * DSW = ' *I4) 

101 GOTO 600 ! !EX 

102 550 WRITE (5*560)IDS ! ! EX 

103 560 FORMAT (' ERROR ON 2ND WAIT* DSW = '*I4> !!EX 

104 C 



105 600 CALL EXIT 

106 END 



3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 



♦TITLE 

♦ I DENT 

♦ ENABL. 



LEX83B 

701/ 

LC 



* Enable lower case 



? File LEX83B*MAC 



Second reciever for SNDREF (modifed to LEX83A)* 

Program to recei ve-bw-ref erence (mapped on creation)* 

modify the first data byte in the resiion* 

read ASCII data from the resfion* detach from the 

region and exit* The region will be deleted on last 

detach* 

The first word in the region contains the count of the 
number of bytes of data in the region* 

Assemble and task build instructions* 

.•••MACRO/LIST LB: CI * LIPROGM ACS/LIBRARY *dev: Cufd 3 
->LEX83B 

LINK/MAP/OPTIONS LEX83B * LB : C 1 * 1 UPROGSUBS/LIBRARY 
option? WNDWS-1 
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Dynamic Regions 



SOLUTION 



PROGRAM LEX83B 

C 

C File LEX83B ♦ FTN 
C 

C L.EX83B receives by reference a region from the task 
C LEX83A* It maps to the region* modifies the first 
C bytey prints out the contents? and exits* The region 
C is deleted on last detach* 
C 

C Task -build instructions J Include these options 
C WNDWS=1 

c vsect=data: 160000 : 20000 

c 

C Install and run instructions* LEX83B must be installed* 
C as RCVRF2 ♦ RCVREF must be installed* Run LEX83A first r 
C then run LEX83B and RCVREF (in either order)* 



C 

C WDB ~ Window definition block witht 
C APR 7 

C Si He 200(8) 32-word blocks 

C Allow for full APR 

C Offset in region 32-word blocks 

C Length of region 32- word blocks (to be filled 

C in on receive) 

C Read and write access 

INTEGER WDB (8) 

DATA WDB/"3400?Oy " 2 y y y "0y "3*0/ 
BYTE DATA (128) 



C This common block will align with the address window 
COMMON /DATA/DATA 

C 

C Create address window — do not map at this time 

CALL CRAW ( WDB y IDS) 
C Check for error on create 

IF (IDS ♦ LT ♦ 0) GOTO 200 
C Now set WDB status for mapping — will be done by 
C recei ve-by-ref erence 

WDB<7)=WDB(7)+"200 
C Receive data and map 

CALL RREF(WDBy y IDS) 
C Check for error 

IF ( IDS ♦ LT ♦ 0) GOTO 100 
C Modify first value 

DATA( 1 ) ~ ' 9 ' 

C Calculate number of bytes of data - length in blocks 
C returned at WDB(6) 

NCHAR = 64*WDB(6) 

WRITE(5ylO) ( DATA ( I ) y 1 = 1. y NCHAR) 
10 FORMAT (' ' y 64 A 1 ) 

C Go exit 

GOTO 300 
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File I/O 



TEST/EXERCISE 

Next to each activity, write for open, I for I/O operation, 
or C for close, to identify which step of file I/O is 
involved. 

a. Records are read from the file. 



b. Access rights to the file are checked. 



c. Existing file is located on disk. 

d. Internal buffers are placed in a pool for re-use. 

e. Records are written to a file. 



Describe three functions performed by the Files-11 ancillary 
control processor (F11ACP) when a task creates a new file 
containing seven blocks. 
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File I/O 



TEST/EXERCISE 



A company has a file of customer records. Each record 
contains the company name, the address, the contact 
person, and the equipment bought. At different times, the 
records are accessed using company name, city, or contact 
person . 



A company uses COBOL for its applications. It has a 
payroll file which is processed in order every two weeks. 
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File I/O 



SOLUTION 

Next to each activity, write for open, I for I/O operation, 

or C for close, to identify which step of file I/O is 
involved. 



I 


a . 


Records are read from the file. 





b. 


Access rights to the file are checked. 





c . 


Existing file is located on disk. 


c 


d. 


Internal buffers are placed in a pool for re-use. 


I 


e . 


Records are written to a file. 



Describe three functions performed by the Files-11 ancillary 
control processor (F11ACP) when a task creates a new file 
containing seven blocks. 

Any three of the following: 

Allocate a file header 
Initialize the file header 
Set up file retrieval pointers 
Create a directory entry 
Allocate blocks to the file 
Connect a task's LUN to the file 
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File I/O 



SOLUTION 



A company has a file of customer records. Each record 
contains the company name, the address, the contact 
person, and the equipment bought. At different times, the 
records are accessed using company name, city, or contact 
person. 

Best answer is RMS only since an indexed file with 
multiple keys is needed for fastest access. FCS can be 
used, but access by key value is impossible. You would 
have to step through the file, checking all records, to 
locate the one you want. 

A company uses COBOL for its applications. It has a 
payroll file which is processed in order every two weeks. 

RMS only; COBOL is supported under RMS, but not under 
FCS. 
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File Control Services 



TEST/EXERCISE 



1. Modify CRESEQ so that each record in the file contains the 
text input from the terminal preceded by "AAAA" . 

2. Write a task that appends records to a file you have created 
(using one of the FCS example programs or the editor) . 

3. In MACRO-11, modify the task CREFXA so that input from the 
terminal uses FCS routines instead of QIO directives. 

4. Write a task that requests input from a terminal of the form: 

n, text 

Use the input to update the nth record of FIXED. ASC , which has 
fixed length records. Use random access and do not truncate 
the file. 

5. In MACRO-11, modify the task BL0CK1 or BL0CK2 so that it 
writes or displays two virtual blocks at a time. 

6. (Optional) In MACRO-11, modify the task CSI so that the 
subroutines DISPLY and DELETE actually display and delete the 
file. Caution: DELET$ delete the highest version of a file 
if no version number is specified. (See Chapter 6 of the 
IAS/RSX I/O Operations Reference Manual for information about 
the routines GCML and CSI.) 
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File Control Services 



SOLUTION 



l. 



3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦ TITLE C RES EG 
♦I DENT /Ol/ 
♦ ENABL LC 

File LEX101»MAC 

Modified to preced each record with AAAA 

CRESEQ creates a file VARI»ASC* It reads 
records from Tl'fy and places them in the file* 
A ~Z terminates input and closes the file* 

Assemble and task-build instruct ions? 

MACRO/LIST LB: CI ? 1 3PR0GMACS/LIBRARY y dev : Cuf d."J- 
••->CRESEG 

LINK /MAP CRESEQ? LB* CI r 1 3PR0GSUBS/LIBRARY 

♦MCALL EXST$CyQI0W*CyQ10W$yDIR* r System macros 

♦ MCALL FSRSZ* y FDBDF* y FDAT$ A y FDRC*A y FDQP$A y 
♦ MCALL NMBLK*yOPEN*Wy PUT* y CLOSE* ? 

♦ MCALL D I R E R Ry 10 E R R y F C S E R R ? S u p plied m a c r o s 

FSRSZ* 1 y 1 file for record I/O 

y Define file descriptor block for VARI»ASC 
FDB ♦ 



FDBDF* 
FDAT*A R ♦ VAR y FD ♦ CR 



FDRC*A y BUFF 



FD0F*A 



FNAME 



FNAME: NMBLK* VARIyASC 

y Local Data 

buff: ♦ asci i /aaaa/ 

inbuf: .blkb so* 

iost: ♦ blkw 2 



Allocate the FDB 
Variable length records y 
L i s t i n g - i in p 1 i e d 
ca r r i asie retu rn y 1 i ne 
feed 

Seauential access and 
record I/O by 
default y BUF r F is 
user record buffer 

Use LUN ly file spec 
at FNAME 

"VARI ♦ ASC" 



USER RECORD BUFFER 
I/O STATUS BLOCK 



y y EX 
y y*EX 



♦ LIST 

♦ EVEN 



BEX 



♦ENABL LSB 
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File Control Services 



SOLUTION 



1 

2 


C 




PROGRAM CRESEQ (CREATE FILE SEQUENTIALLY 


3 


C 


FILE 


LEX101 ♦ FTN 


4 


C 






5 


C 


Modified to precede each record with AAAA !!EX 


6 


C 






7 


C 


This 


task creates a file of VARI»ASC of 


8 


C 


variable-length records using sequential record acce 


9 


C 


The 


records are input from the terminal and copied ti 


10 


C 


the 


file* The process stops when the operator types 


11 


C 


CTRL/Z 3t the terminal* 


12 


C 






13 






BYTE BUFF (84) , INBIJF<80> HEX 


14 






EQUIVALENCE < BUFF < 5 ) > INBUF < 1 ) ) HEX 


15 






INTEGER LEN 


16 






DATA BUFF < 1 ) >-BUFF<2> r BUFF ( 3 ) ,BUFF<4) 


17 






1 /' A' > ' A' r 'A' > 'A'/ 


18 


C 






19 


c 






20 


c 


OPEN 


FILE 


21 


c 






22 


c 


Default access is sequential 


23 


c 


Default is formatted 1/0 for sequential files 


24 


c 






25 






OPEN <UNIT=1»NAME*'VARI.ASC / r TYPE™ ' NEW ' > 


26 






1 CARRIAGEC0NTR0L~ 'LIST ' > 


27 


c 






28 






TYPE * r ' TYPE IN TEXT, TERMINATE EACH RECORD 


29 






1 WITH A CARRIAGE RETURN' 


30 






TYPE % f ' TERMINATE INPUT WITH A CTRL/Z' 


31 


c 


Loop 




32 


10 


READ <5>11>END=100> LENv INBUF ! Read record! 


33 


11 




FORMAT (QrSOAl) 


34 


c 






35 






LEN = LEN+4 ! Add 4 for A'< 


36 


c 




! 


37 






WRITE (lrl2) (BUFF (Drl^lr LEN) ! Write record 


38 


12 


FORMAT (80A1) ! to file 


39 






GO TO 10 


40 


c 


Close file and exit 


41 


100 


CLOSE (UNIT=1) 


42 






CALL EXIT 


43 






END 
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51 




qioui*c 


I0.RVB>5>1> r IOST> 


><BUFF?80»>? Read a 


52 








line from TI* 


53 




BCC 


DIROK ? 


Branch on Directive ok 


54 




MOV 


♦EFIQIOrRi r 


Set up for *EDMSG 


55 




MOV 


#*DSU»R2 t 




56 




BR 


SHOERR i 


Branch to show error 


57 








and exit 


58 


dirok: 


TSTB 


IOST r 


Check for I/O error 


59 




BGT 


OKIO f 


Branch if I/O ok 


60 




CMPB 


#IE*EOF>IOST i 


Check for EOF 


61 




BEG 


EXIT ? 


If EQr close and exit 


62 




MOVB 


lOSTrRO i 


I/O status is si^n 


63 








extended and placed 


64 








in argument block 


65 




MOV 


RO y ARG i 


for *EDMSG call 


66 




MOV 


*ARG , R2 i 


Set up for *EDMSG call 


67 




MOV 


#EFDQI0?R1 f 




68 




BR 


SHOERR i 


Branch to show error 


69 








and exit 


70 


okio: 


MOV 


I0ST+2,R1 9 


Length of record to Rl 


71 




PUT* 


♦FDBy rRl »ERR2 r 


Write next record 


72 




BR 


10* f 


Get next record 


73 










74 


exit: 


CLOSE* 


#FDB ? 


Close file 


75 




BCS 


ERR3 r 


Branch on PCS error 


76 




EXST*C 


EX*SUC i 


Exit with status of 1 


77 










78 


f Error 


Processing 




79 


ERR1 ♦ 








80 


ERR2 J 








81 


ERR 3 ♦ 


TSTB 


F ♦ ERR+1 < RO ) ? 


Directive error or I/O 


82 








error 


83 




BEQ 


10 ? 


Branch on I/O error 


84 




MOV 


♦EFCDIR rRl t 


Set up for *EDMSG 9 


85 








directive error 


86 




BR 


FINSET 9 


Branch to finish setup 


87 


io: 


MOV 


♦EFCSIOrRl ? 


Set up for *EDMSG 9 I/O 


88 








error 


89 


finset: 


MOVB 


F ♦ ERR (RO ) rRO t 


FCS error code 


90 




MOV 


R0» ARG ? 


is sign extended and 


91 




MOV 


#AR6 * R2 ? 


placed in arg block 


92 








*EDMSG argument block 


93 


shoerr: 


MOV 


#OBUFF ? RO ? 


Output buffer 


94 




CALL 


*EDMSG r 


Format error message 


95 




MOV 


RlrPRINT+G*I0PL+2 


9 Size of message 


96 




DIR* 


♦PRINT r 


Print error message 


97 




CLOSE* 


#FDB 9 


Close file 


98 




EXST*C 


EX*ERR 9 


Exit with status of 2 


99 




♦ END 


START 
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File Control Services 



SOLUTION 



3. 



1 




♦TITLE 


p 




♦ I DENT 


3 




♦ ENABL 


A 

T 


y + 




5 


f File 


LEX103. 


6 






7 


i Modified to 


(3 


y input 


from T 


o 

7 








i CREFXA opens 


1 1 


r from 


Ti: and 


12 


y A ~z 


termiri3 


13 






14 






15 




♦ MCALL 


16 






17 




♦ MCALL 


18 




♦ MCALL 


19 




♦ MCALL 


20 




♦MCALL 


21 






22 




♦ NLIST 


23 


RSIZ 


= 30* 


24 


iost: 


♦ BLKW 




print: 


QIOW* 


26 


buff: 


♦ BLKB 


27 


obuff: 


♦ BLKB 


28 






29 


arg: 


♦ BLKW 


30 






31 


EFDQIO: 


♦ASCIZ 


32 


efiqio: 


♦ASCIZ 


33 


efcdir: 


♦ ASCIZ 


34 


efcsio: 


♦ ASCIZ 


35 






36 




♦ EVEN 


37 




.LIST 


38 






39 




FSRSZ* 


40 


y 




41 






42 


fdb: 


FDBDF* 


43 




FDRC*A 


44 




FDAT*A 


45 






46 




FD0P*A 


47 


file: 


NMBLK* 



CREFXA 

/01/ 

LC 



? Enable lower case 



f 9 EX 



EXST*CyQIOW*CyQIOW*yDIR* 

FSRSZ* y FDBDF* y NMBLK* 
FDRC* A f FDAT*A y FDOP* A 
0PEN*W y GET* y PUT* y CLOSE* 
0PEN*R 

BEX ? Suppress ASCII 

y Record size (bytes) 
2 y QIO status block 

1 ♦ WMB y 5 y 1 y y y y <0BUFF y t 40> 

RSIZ y User record buffer 

80* ? Output buffer for 

? error messages 
1 y Argument block for 

? *EDMSG 

/DIRECTIVE ERROR ON QIO* ERROR CODE = ZD./ 
?I/0 ERROR ON QIO. ERROR CODE = ZD.? 
/FCS DIRECTIVE ERROR ♦ ERROR CODE = ZD./ 
?FCS I/O ERROR CODE ♦ ERROR CODE = ZD.? 



BEX 



y Show offsets 



y 2 files for 



record I/O 
? ?EX 



y BUFF y RSIZ 

R ♦ FIX yFD.CRy RSIZ 

lyyFILE i 
FIXEDy ASC i 



File descriptor block 
User buffer and size 
: Fixed length records y 
implied < C R > < L F > 
use LUN 1 
FIXED. ASC 
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SOLUTION 



98 


i Error 


Processing 




99 


erri: 








100 


ERR2J 








101 


ERR 3 ♦ 








102 


ERR4 : 


TSTB 


F»ERR+ 1 <R0) 9 


Directive error or I/O 


103 








error 


104 




BEG) 


10 f 


Branch on I/O error 


105 


mrerr: 


MOV 


♦EFCBIRyRl 9 


Set up for *EDMSG 9 9 9 EX 


106 








directive error 


107 




BR 


FINSET f 


Branch to finish setup 


108 


io : 


MOV 


#EFCSIOyRl ? 


Set up for *EEiMSG> I/O 


109 








error 


110 


finset: 


MOVB 


F»ERR<R0),R0 ) 


FCS error code 


111 


MOV 


ROvARG i 


is si sin extended and 


112 




MOV 


#ARG yR2 9 


placed in arg block 


113 








*EDMSG argument block 


114 


shoerr : 


MOV 


♦OBUFFrRO i 


Output buffer 


115 




CALL 


*EDMSG i 


Format error message 


116 




MOV 


Rl*PRINT+Q*I0PL+2 


i Size of message 


117 




MR* 


♦PRINT 9 


Print error message 


118 




CLOSE* 


#FDB ? 


Close file 


119 




CLOSE* 


♦FDBI 9 


Close "file" at Tli 9 9 EX 


120 




EXST*C 


EX*ERR 9 


Exit with status of 2 


121 




♦ END 


START 
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File Control Services 



SOLUTION 



50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 



ENABL LSB 



start: open*u #fdbi 



y Clear 

io$: 

20$ : 



buffer to all blanks 
MOV #RSIZyRl 
MOV *BUFFyR2 
MOVB *' y(R2)+ 
SOB Rly20* 



r Allow local symbols 
y to cross Psect 
i boundaries 

yyERRl i Open file for update 
$ (includes extend) 

each time 

y Record size 

? R2 => buffer 

y Move in a bl3nk 

y Continue until done 



y Check 



QI0W*C I0.RPRy5yly y I0ST y y <BUFF y RSIZ t y INPT y LINPT y ' *.' 

y Prompt and get input 
Check for ~Z 
If "Zy exit 
Set up to convert 
record # to binary 
after * is 



CMPB 

BEG) 

MOV 

CALL 

for 



#IE.E0Fy I0ST 
EXIT 

♦BUFFyRO 
*CDTB 

good conversion y character 
returned in R2 (it should be a "y") 

CMPB #"yyR2 ? Is it a comma 

BEG GOOD y Branch on good 

? conversion 

HKWVBySyly y y y -XNVER y LCNVER y 40> 

y Display error message 



GI0W*C 
BCS 



good: 



y Close 

exit: 



ERR1 : 
ERR2 : 
ERR3 : 



ioerr: 



BR 

PUT*R 
BR 

f iley 
CLOSE* 
GI0W*C 

BCS 

EXIT*S 



CLOSE* 

MOVB 

MOV 

MOV 
TSTB 
BEG. 
MOV 

BR 
MOV 



ERR4 
10* 

*FDB y y yRly yERR2 



Branch 



di recti ve 



output 



10* 

display 



message y 



#FDB yERR3 
I0»WVBy5yly y y y 

ERR4 



#FDByERR3 
F*ERR(R0) yRO 
ROylOST 

#I0STyR2 
F,ERR+1(R0) 
IOERR 
♦EMESDyRl 

COMME 
#EMESIyRl 



on 

error 
Get next input 
Write record to 
y file 

y Get next input 
and exit 

? Close file 
(BUFF 1 y LEN 1 y 40> i W r i te 
y message to operator 
y Branch on error 



Close file 

Move FCS error code 

to argument block 

for *EDMSG 
Set up for *EDMSG 
I/O or directive error 
Branch on I/O error 
Set up for dir error 

message 
Branch to common code 
Set up for 1/0 error 

message 
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SOLUTION 



5. 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦ TITLE BL0CK2 

♦ I DENT /01/ 
♦ENABL LC 



? File? LEX105.MAC 



r Enable lower esse 
r r EX 



? Modified to work on 2 virtual blocks 3t a time ??EX 
y 

) ##-BL0CK2 prompts 3t Tit for a virtual block number 

? and then reads and displays that block of "BLOCK .ASC 



♦MCALL QI0W*yDIR*yQI0W*SyEXST*S 

♦ MCALL. FDBDF* r FDRC*A y FDBK*A r FD0P*A x NMBLK* 

♦ MCALL FSRSZ* y0PEN*Ry READ* y WAIT* y CLOSE* 



SBTTL MESSAGES 

NLIST BEX 
= 15 
= 12 

ASCII /FIRST VIRTUAL BLOCK: / 
* ♦ - MES1 

ASCII < C R > < L. F > /HERE ARE THE BLOCKS 



CR 
LF 

mesi: 

LENl 
MES2 * 
r 

LEN2 
MES3I * 
MES3D ♦ 
MES4I t 
MES4D ♦ 
MES5I t 
MES5D t 

buff: 



fdb : 



file: 



HEX 

/<CRXLF> 
f ?EX 



= . - MES2 

ASCIZ 'I/O ERROR 

ASCIZ /DIRECTIVE 

ASCIZ 'I/O ERROR 

ASCIZ /DIRECTIVE 

ASCIZ 'I/O ERROR 

ASCIZ /DIRECTIVE 

BLKB 80* 



FROM 0PEN*Ry CODE = ZD.' 
ERROR FROM 0PEN*Ry CODE = ZD./ 
FROM READ* » CODE ~ ZD.' 
ERROR FROM READ* y CODE - %D./ 
FROM WAIT*y CODE = ZD*' 
ERROR FROM WAIT*y CODE = ZD./ 
t STORE RESPONSE HERE 



.LIST 
.EVEN 
.SBTTL 



BEX 



.OCAL STORAGE 



FSRSZ* 



NO FSR BUFFER NEEDED 
FOR BLOCK I/O 



FDBDF* 
FDRC*A 
FDBK*A 

FDOP*A 
NMBLK* 



t FDB FOR INPUT FILE 
FD.RWM 9 READ/WRITE MODE 

BLOCK* 1024 .rtl> IOSB 9 EF 1 ? BUFFER ADRr r f EX 

y SIZE 

1 r y FILE f LUN lv DFNB 

BLOCK y ASC y NAME IS BLOCK .ASC 



vbn: .WORD 
block: .blkw 
iosb: .blkw 



Oyl 
512. 



DEFAULT VBN 
BLOCK BUFFER 



y y EX 
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101 

102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 



I0ERR2 i MOV 
BR 

ERR 3 : 

TSTB 
BEQ 
MOV 
BR 

I0ERR3: MOV 



fcserr: 



FORMAT 



exit: 



MOVB 

MOV 

MOV 

MOV 
MOV 
CALL 
QIOW*S 



CLOSE* 
EXST*S 
♦ END 



#MES4I,R1 

FCSERR 

F»ERR+1 <R0) 
I0ERR3 
♦MESSED Rl 
FCSERR 
*MES5I>R1 



F»ERR(RO) tR2 
R2> IOSB 
#EX*ERR»R5 

*I0SB>R2 
#BUFF»R0 
$EDMSG 

*I0.WVBy#5y#l > 9 , 



#FDB 

R5 

START 



=> I/O error message 4 
Branch to common code 

I/O or directive error 
Branch on I/O error 
~> Dir error message 5 
Branch to common code 
--> I/O error message 5 
FALL INTO COMMON CODE 

Si3n extend error code 

and move into IOSB 
Exit status in R5 

Set up for *EDMSG 



:*BUFF»R1,#40> ? Display 
message 

Close the file 
Exit with status 
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SOLUTION 



51 CSI* 9 Define CSI offsets 

52 CBLK: .BLKB C.SIZE 9 allocate CSI storage 

53 ♦ EVEN 
54 

55 DEMSK = 1 f Delete mask 

56 DIMSK = 2 t Display mask 

57 SUTBL* 9 Switch descriptor table 

58 CSI$SW DEy DEMSK 9 Delete switch = DE 

59 CSI*SW DI yDIMSKy r y yNUM 9 Display switch = Dly 

60 9 also 3llow DUN 

61 CSI*ND 9 End of switch table 
62 

63 CSI*SV OCTAL y COPY y 2 y NUM 9 Value N for /DUN is 

64 9 in octal 3nd will 

65 9 be stored in COPY 

66 CSI*ND 9 End of switch value 

67 9 table 

68 ?GET COMMAND LINE BLOCK DEFINITIONS 
69 

70 FSRSZ* 3 9 GCML uses record I/0?yEX 
71 

72 GBLK: GCMLB* yCSIyyS 9 Prompt with 'CSI' on 

73 9 LUN 5 

74 FDBt FDBDF* 9 FDB for file to delete 

75 9 or display* 

76 FDRC*A y TBUFF y 132* 9 URB AT TBUFF r length 

77 9 132. 

78 FD0P*A lyCBLK+C.DSDS f LUN 1» dataset 

79 9 descriptor from CSI 
80 

81 9 NOTE? Need a 2nd FDB for display 
82 

83 FDBO: FDBDF* 9 FDB for output to TU??EX 

84 FDAT$A R. VARyFD.CR y V3r length records y y?EX 

85 9 list format yyEX 

86 FDRC*A , TBUFF y 132. 9 URB at TBUFF y length 9 9 EX 

87 9 132. ??EX 

88 FD0P*A 2>DSPT0 i LUN 2r dataset y?EX 

89 f descriptor at DSPTO y?EX 

90 DSPTOi ♦ WORD LDEVyDEV 9 Dataset descriptor yyEX 

91 ♦ WORD OyO 9 for TU . No UIC or yyEX 

92 .WORD OyO 9 name needed. yyEX 

93 DEV: .ASCII /TU/ f 9 9EX 

94 LDEV=.-DEV 9 9 9 EX 
95 

96 ♦ EVEN 

97 JMPTBL: .WORD NONE y DELETE y DISPLY y Jump table for 

98 y subroutines depending 

99 9 on switches 

100 COPY: .WORD 1 y Value for N in /DUN 
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151 CALL OUTMS ? Call OUTMS y as a ??EX 

152 ? subroutine ??EX 

153 RETURN ? Return ??EX 
154 

155 ? Common display message code ~ a subroutine since it ??EX 

156 ? is not a common return point ??EX 
157 

158 OUTMS : MOV #BUFFyRO J Set up for $EDMSG 

159 MOV *FMT yRl ? 

160 MOV #DATAyR2 ? 

161 CALL $EDMSG y Edit message 

162 QI0W*S #I0*WVBy#5y#ly ft y<*BUFFyRl y #40> ? Display 

163 RETURN ? Return 
164 

165 ? Subroutine DELETE 

166 ? 

167 ? ***WARNING - THE HIGHEST VERSION NUMBER OF THE FILE *** 

168 ? ***WILL BE DELETED IF NO VERSION NUMBER IS SPECIFIED *** 
169 



170 


delete: 


MOV 


♦ DELTXT y DATA ? 


Set up for output of 




171 








message 




172 




CALL 


OUTMS ? 


C3ll display 


? ?EX 


173 








subroutine 


? 5 EX 


174 




DELET* 


♦FDBrERRD ? 


Delete file 


? ? EX 


175 




RETURN 




Return 




176 


? Delete error 


code 






177 


ERRD : 


MOVB 


F»ERR<RO) yR5 ? 


Extend sign on error?? EX 


178 




MOV 


R5 i DATA+2 ? 


and move to srsi block?? 


179 




MOV 


♦DELTXT y DATA ? 


Move pointer to delete?? 


180 








text 


? ?EX 


181 


COMME.* 


TSTB 


F.ERR+1 (RO) ? 


Check for directive 


? ?EX 


182 








error or I/O error 


? ?EX 


183 




BEQ 


IOERR ? 


Branch on I/O error 


? ? EX 


184 




MOV 


♦FMTERDyRl ? 


Get format string 


? ?EX 


185 




BR 


DISPER ? 


Branch to common 


? ? EX 


186 








error display code 


? ?EX 


187 


ioerr: 


MOV 


♦FMTERI y Rl ? 


Get format string 


? ? EX 


188 


disper: 


MOV 


♦BUFFyRO ? 


Set up for *EDMSG 


? ? EX 


189 




MOV 


#DATAyR2 ? 




? ?EX 


190 




CALL 


$EDMSG ? 


Edit message 


? ?EX 


191 




MOV 


RlyTYPE4+Q»I0PL+2 


? Size of message 


? f EX 


192 




DIR* 


♦TYPE4 ? 


Display message 


??EX 


193 




EXIT*S 




Exit 


? ?EX 


194 












195 


? Subroutine DISPLY - Just display a message 




196 












197 


disply: 


CALL 


*SAVAL y 


Save all registers 




198 




MOV 


♦DITXTyDATA ? 


Set up for output of 




199 






? 


message 




200 




CALL 


OUTMS ? 


Branch to common 




201 






? 


display code 
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